@remcp/runtime 0.2.102 → 0.2.104

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.104 — 2026-09-22
+
+- Fresh installations default the narrow catastrophic-command guardrail to block; ordinary development, file, Git, package-manager, Docker, database and browser workflows remain available, and explicit warn, allow, or unrestricted/godmode remain operator-controlled opt-ins.
+- macOS top-level window handles include a snapshot generation and retain short-lived app/title/bounds identity so window reordering cannot silently retarget a previous id.
+- A valid prior macOS handle resolves the same uniquely identifiable window after reorder; unknown, ambiguous, expired, PID-mismatched and legacy ids fail closed and request a fresh list_windows.
+- Added 73 Desktop Commander prompt scenarios as an isolated compatibility smoke matrix; all 73 passed on the release tree with no guardrail false positives. GNOME Wayland live computer-use passed 80/80 checks.
+
+## 0.2.103 — 2026-09-22
+
+- Native Wayland `window_action` targets exact PID/title Accessibility windows for `close` and verifies that the requested window disappeared.
+- Shortcut-backed Wayland window actions require verified focus on the exact requested window before minimize, maximize, move, resize, or close proceeds; ambiguous targeting fails closed.
+- Live smoke coverage isolates XDG open/reveal handlers and stabilizes browser input focus without changing the runtime tool surface.
+- Verified on GNOME Wayland with 80 passing computer-use checks and a two-window isolation proof: target A closed while sibling B stayed open.
+
 ## 0.2.102 — 2026-09-22
 
 - `runWithInput` installs a stdin error handler before writing input, so an early child pipe close is returned as a `ToolError` instead of an uncaught `EPIPE` that can terminate the runtime.

package/README.md

@@ -147,10 +147,10 @@ in `~/.config/remcp/runtime.json`. `--describe` always reports the current state
   against the resolved real path of the deepest existing ancestor rather than the lexical string, so
   `<allowed>/link -> /etc` cannot be used to read or write outside the allowed directories.
   `allowedRoots: ["/"]` means the whole filesystem and works as written.
-- **Command guardrail.** `dangerousCommands` defaults to `warn`: a catastrophic command still runs and
-  the result carries a note. `allow` silences the note, `block` refuses before running. Rules match the
-  *command word* of each shell segment, so `grep -n format README.md` is never affected. User
-  `blockedCommands` entries are always enforced.
+- **Command guardrail.** `dangerousCommands` defaults to `block`: a catastrophic command is refused
+  before execution. Operators can explicitly choose `warn` to run it with an advisory note or `allow`
+  to disable the built-in guardrail. Rules match the *command word* of each shell segment, so
+  `grep -n format README.md` is never affected. User `blockedCommands` entries are always enforced.
 - **A bad configuration is loud.** If `runtime.json` cannot be parsed, the device refuses to start and
   says why, instead of quietly dropping your `allowedRoots` and re-enabling usage metrics.
 - **Secret masking.** `list_processes` masks command arguments that look like tokens, passwords, or
@@ -182,7 +182,7 @@ Optional settings live in `~/.config/remcp/runtime.json` (override the directory
   "name": "workstation",
   "allowedRoots": ["~/projects", "/srv/data"],
   "blockedCommands": ["rm -rf /", "shutdown"],
-  "dangerousCommands": "warn",
+  "dangerousCommands": "block",
   "telemetryEnabled": true,
   "maxOutputBytes": 1048576,
   "maxReadLines": 2000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.102",
+  "version": "0.2.104",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -61,10 +61,9 @@ function booleanValue(value, fallback) {
 
 const DANGEROUS_MODES = ['block', 'warn', 'allow'];
 
-// `warn` runs the command and adds a note when it matches the destructive-command list:
-// nothing is ever blocked or delayed, but a catastrophic command is visible in the tool
-// result. Set `allow` for zero noise or `block` to refuse.
-function dangerousMode(value, fallback = 'warn') {
+// `block` is the secure default: matching catastrophic commands are refused before execution.
+// Operators can explicitly choose `warn` to run with an advisory note or `allow` for zero guardrail noise.
+function dangerousMode(value, fallback = 'block') {
   const normalized = String(value ?? '').trim().toLowerCase();
   return DANGEROUS_MODES.includes(normalized) ? normalized : fallback;
 }

package/src/extended/desktop-linux.mjs

@@ -312,19 +312,100 @@ async function verifyNativeWaylandGeometry(row, expected, label) {
   throw new Error(`Could not verify native Wayland window ${label} for ${row.title || row.app || row.id}: wanted ${wanted}; observed ${actual}`);
 }
 
+async function nativeWaylandAccessibilityAction(row, actionNames) {
+  const pid = Number(row?.pid);
+  if (!Number.isInteger(pid) || pid <= 0 || !Array.isArray(actionNames) || !actionNames.length) {
+    return { applied:false, available:[] };
+  }
+  const script = pyAtSpiPrelude() + `
+want_pid=${pid};want_window=${JSON.stringify(String(row.title || ''))};wanted_actions=${JSON.stringify(actionNames)}
+target=None
+for root,app_name,pid,active in q:
+ if pid!=want_pid: continue
+ try:
+  for child in root:
+   try:
+    role=(child.getRoleName() or "").lower();name=child.name or ""
+    if role not in ("frame","window","dialog"): continue
+    if want_window and want_window.strip().lower()!=name.strip().lower(): continue
+    target=child;break
+   except: pass
+ except: pass
+ if target is not None: break
+if target is None:
+ print(json.dumps({"applied":False,"available":[],"reason":"target window not found"}))
+else:
+ try:
+  actions=target.queryAction();available=[];chosen=-1;chosen_name=""
+  for i in range(actions.nActions):
+   try: action_name=actions.getName(i) or ""
+   except: action_name=""
+   available.append(action_name)
+   if chosen<0 and action_name in wanted_actions:
+    chosen=i;chosen_name=action_name
+  if chosen<0:
+   print(json.dumps({"applied":False,"available":available,"reason":"requested accessibility action unavailable"}))
+  else:
+   applied=actions.doAction(chosen)
+   if applied is False: raise Exception("accessibility window action returned false")
+   print(json.dumps({"applied":True,"action":chosen_name,"available":available}))
+ except Exception as exc:
+  print(json.dumps({"applied":False,"available":[],"reason":str(exc)}))
+`;
+  const result = await runFile('python3', ['-c', script], { label:'AT-SPI window action', timeout:2000, allowFailure:true });
+  try {
+    const payload = JSON.parse(result.stdout || '{}');
+    return payload && typeof payload === 'object' ? payload : { applied:false, available:[] };
+  } catch {
+    return { applied:false, available:[], reason:String(result.stderr || result.stdout || 'AT-SPI window action failed').trim() };
+  }
+}
+
+async function verifyNativeWaylandWindowClosed(row, timeoutMs = 2500) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try { await windowMatch({ id:row.id }); }
+    catch { return; }
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`Could not verify native Wayland window close for ${row.title || row.app || row.id}`);
+}
+
+async function focusNativeWaylandForAction(row, backend) {
+  await windowAction({ action:'focus', id:row.id, backend });
+  const focusState = await targetAccessibilityFocus(row);
+  if (!focusState.exact) throw new Error(`Could not verify native Wayland focus for ${row.title || row.app || row.id}`);
+}
+
 async function nativeWaylandWindowAction(row, action, args) {
   const backend = inputBackend(args);
   if (backend === 'x11') unavailable('Native Wayland window action', 'use backend=portal for compositor-managed windows');
   if (!waylandPortalCandidate()) unavailable('Native Wayland window action', 'no XDG RemoteDesktop portal is available');
   if (backend === 'auto' && !hasWaylandRemoteDesktopGrant()) portalPermissionHint('Native Wayland window action');
-  if (row.ui_id) {
-    try { await uiAction({ action:'focus', id:row.ui_id }); } catch {}
-  }
 
   const portalBackend = backend === 'portal' ? 'portal' : 'auto';
   const timeoutMs = backend === 'portal' ? 120_000 : 2500;
-  if (action === 'close') await portalShortcut('ALT+F4', { timeoutMs });
-  else if (action === 'minimize') await portalShortcut('ALT+F9', { timeoutMs });
+  if (action === 'close') {
+    const semantic = await nativeWaylandAccessibilityAction(row, ['window.close']);
+    if (semantic.applied) {
+      await verifyNativeWaylandWindowClosed(row);
+      return jsonResult({ action, backend:'atspi-window-action', id:row.id, accessibility_action:semantic.action });
+    }
+    // Some GTK apps disconnect from AT-SPI while handling window.close, before the action
+    // call can return a success payload. Trust the observed target state, not that race.
+    try {
+      await verifyNativeWaylandWindowClosed(row, 400);
+      return jsonResult({ action, backend:'atspi-window-action', id:row.id, accessibility_action:'window.close', verified_after_disconnect:true });
+    } catch {}
+    await focusNativeWaylandForAction(row, portalBackend);
+    await portalShortcut('ALT+F4', { timeoutMs });
+    await verifyNativeWaylandWindowClosed(row);
+    return jsonResult({ action, backend:'xdg-desktop-portal', id:row.id });
+  }
+  if (action === 'minimize') {
+    await focusNativeWaylandForAction(row, portalBackend);
+    await portalShortcut('ALT+F9', { timeoutMs });
+  }
   else if (action === 'maximize' || action === 'restore') {
     let maximized = false;
     try {
@@ -346,9 +427,11 @@ async function nativeWaylandWindowAction(row, action, args) {
       }
     } catch {}
     if ((action === 'maximize' && !maximized) || (action === 'restore' && maximized)) {
+      await focusNativeWaylandForAction(row, portalBackend);
       await portalShortcut('ALT+F10', { timeoutMs });
     }
   } else {
+    await focusNativeWaylandForAction(row, portalBackend);
     let currentX = Number(row.x), currentY = Number(row.y), currentWidth = Number(row.width), currentHeight = Number(row.height);
     if (![currentX,currentY,currentWidth,currentHeight].every(Number.isFinite)) unavailable('Native Wayland window geometry', 'accessibility bounds are unavailable');
 
@@ -495,6 +578,9 @@ except Exception:
    def currentValue(self,v): self.a.set_current_value(float(v))
   class _Action:
    def __init__(self,a): self.a=a
+   @property
+   def nActions(self): return self.a.get_n_actions()
+   def getName(self,i): return self.a.get_action_name(i)
    def doAction(self,i): return self.a.do_action(i)
   class _Editable:
    def __init__(self,a): self.a=a

package/src/extended/desktop-macos.mjs

@@ -23,6 +23,72 @@ function parseTsv(value, fields) {
   });
 }
 
+const macWindowTargets = new Map();
+const MAC_WINDOW_TARGET_TTL_MS = 5 * 60 * 1000;
+let macWindowGeneration = 0;
+
+function rememberMacWindowTarget(row) {
+  macWindowTargets.set(row.id, {
+    pid:row.pid,
+    app:row.app,
+    title:row.title,
+    x:row.x,
+    y:row.y,
+    width:row.width,
+    height:row.height,
+    at:Date.now(),
+  });
+}
+
+function cachedMacWindowTarget(id) {
+  const cached = macWindowTargets.get(id);
+  if (!cached) return null;
+  if ((Date.now() - cached.at) > MAC_WINDOW_TARGET_TTL_MS) {
+    macWindowTargets.delete(id);
+    return null;
+  }
+  return cached;
+}
+
+export function macWindowId(pid, windowIndex, generation) {
+  const numericPid = Number(pid);
+  const numericIndex = Number(windowIndex);
+  const numericGeneration = Number(generation);
+  if (!Number.isInteger(numericPid) || numericPid <= 0
+    || !Number.isInteger(numericIndex) || numericIndex < 0
+    || !Number.isInteger(numericGeneration) || numericGeneration <= 0) {
+    throw new Error('Could not construct a macOS window id from invalid PID/index/generation');
+  }
+  return `mac:${numericPid}:w${numericIndex}:g${numericGeneration}`;
+}
+
+export function normalizeMacWindowTarget(args = {}, { useWindowId = false } = {}) {
+  const explicitPid = Number.isInteger(Number(args.pid)) && Number(args.pid) > 0 ? Number(args.pid) : 0;
+  let idPid = 0;
+  let windowIndex = null;
+  const rawId = useWindowId ? optionalString(args.id) : '';
+  let cached = null;
+  if (rawId) {
+    const match = /^mac:(\d+):w(\d+):g(\d+)$/.exec(rawId);
+    if (!match) throw new Error('macOS window id is stale or unsupported; call list_windows again');
+    idPid = Number(match[1]);
+    windowIndex = Number(match[2]);
+    if (explicitPid && explicitPid !== idPid) throw new Error('macOS window id and pid refer to different processes');
+    cached = cachedMacWindowTarget(rawId);
+  }
+  return {
+    id:rawId,
+    idCached:Boolean(cached),
+    pid:idPid || explicitPid,
+    windowIndex,
+    app:optionalString(args.app) || '',
+    title:optionalString(args.window_title || args.windowTitle || args.title) || '',
+    expectedApp:cached?.app || '',
+    expectedTitle:cached?.title || '',
+    expectedBounds:cached ? [cached.x,cached.y,cached.width,cached.height] : null,
+  };
+}
+
 export async function listWindows() {
   const script = `
 set output to ""
@@ -31,22 +97,30 @@ tell application "System Events"
   try
    set appName to name of p
    set appPid to unix id of p
+   set windowIndex to 0
    repeat with w in windows of p
     try
      set pos to position of w
      set sz to size of w
-     set output to output & appPid & tab & appName & tab & (name of w) & tab & (item 1 of pos) & tab & (item 2 of pos) & tab & (item 1 of sz) & tab & (item 2 of sz) & linefeed
+     set output to output & appPid & tab & windowIndex & tab & appName & tab & (name of w) & tab & (item 1 of pos) & tab & (item 2 of pos) & tab & (item 1 of sz) & tab & (item 2 of sz) & linefeed
     end try
+    set windowIndex to windowIndex + 1
    end repeat
   end try
  end repeat
 end tell
 return output`;
   const { stdout } = await runOsa(script, { label: 'list windows' });
-  const rows = parseTsv(stdout, ['pid','app','title','x','y','width','height']).map((row,index)=>({
-    id:`mac:${row.pid}:${index}`,pid:Number(row.pid),app:row.app,title:row.title,
+  macWindowGeneration += 1;
+  const generation = macWindowGeneration;
+  const rows = parseTsv(stdout, ['pid','window_index','app','title','x','y','width','height']).map(row=>({
+    id:macWindowId(row.pid,row.window_index,generation),pid:Number(row.pid),app:row.app,title:row.title,
     x:Number(row.x),y:Number(row.y),width:Number(row.width),height:Number(row.height),
   }));
+  for (const [id,cached] of macWindowTargets.entries()) {
+    if ((Date.now() - cached.at) > MAC_WINDOW_TARGET_TTL_MS) macWindowTargets.delete(id);
+  }
+  for (const row of rows) rememberMacWindowTarget(row);
   return jsonResult(rows);
 }
 
@@ -67,7 +141,7 @@ export async function windowAction(args = {}) {
   if((action==='move'||action==='move_resize')&&(!Number.isFinite(x)||!Number.isFinite(y)))throw new Error('x and y are required for window move');
   if((action==='resize'||action==='move_resize')&&(!Number.isFinite(width)||!Number.isFinite(height)||width<=0||height<=0))throw new Error('width and height must be positive for window resize');
   const script=`(function(){
-${macJxaTargetPrelude(args)}
+${macJxaTargetPrelude(args,{useWindowId:true})}
 function perform(e,wanted){let acts=[];try{acts=e.actions()}catch(_){};for(let i=0;i<acts.length;i++){let n='';try{n=String(acts[i].name())}catch(_){};if(n===wanted){acts[i].perform();return true}}return false}
 function setAttr(e,n,v){try{e.attributes.byName(n).value=v;return true}catch(_){return false}}
 const action=${JSON.stringify(action)};
@@ -86,21 +160,58 @@ return JSON.stringify({action,pid:Number(proc.unixId()),app:safeName(proc),windo
   let parsed;try{parsed=JSON.parse(stdout.trim())}catch{parsed={action,backend:'macos-accessibility'}}
   return jsonResult(parsed);
 }
-function macJxaTargetPrelude(args = {}) {
-  const pid = Number.isInteger(Number(args.pid)) ? Number(args.pid) : 0;
-  const app = JSON.stringify(optionalString(args.app) || '');
-  const title = JSON.stringify(optionalString(args.window_title || args.windowTitle || args.title) || '');
+export async function resolveWindowTarget(args = {}) {
+  const script=`(function(){
+${macJxaTargetPrelude(args,{useWindowId:true})}
+let p={};try{p=win.properties()}catch(_){};
+return JSON.stringify({
+  id:${JSON.stringify(optionalString(args.id || args.window_id || args.windowId) || '')},
+  pid:Number(proc.unixId()),app:safeName(proc),title:safeName(win),
+  x:Array.isArray(p.position)?Number(p.position[0]):null,
+  y:Array.isArray(p.position)?Number(p.position[1]):null,
+  width:Array.isArray(p.size)?Number(p.size[0]):null,
+  height:Array.isArray(p.size)?Number(p.size[1]):null,
+  backend:'macos-accessibility'
+});
+})()`;
+  const {stdout}=await runOsa(script,{javascript:true,label:'resolve window target',timeout:30_000});
+  let parsed;try{parsed=JSON.parse(stdout.trim())}catch{throw new Error('Could not resolve macOS window target')}
+  return jsonResult(parsed);
+}
+
+function macJxaTargetPrelude(args = {}, options = {}) {
+  const target = normalizeMacWindowTarget(args, options);
+  if (options.useWindowId && target.id && !target.idCached) throw new Error('macOS window id is stale or unknown; call list_windows again');
+  const app = JSON.stringify(target.app);
+  const title = JSON.stringify(target.title);
+  const expectedApp = JSON.stringify(target.expectedApp);
+  const expectedTitle = JSON.stringify(target.expectedTitle);
+  const expectedBounds = JSON.stringify(target.expectedBounds);
   return String.raw`
 const se=Application('System Events');
-const wantPid=${pid};
+const wantPid=${target.pid};
+const wantWindowIndex=${target.windowIndex == null ? 'null' : target.windowIndex};
 const wantApp=${app};
 const wantTitle=${title};
+const expectedApp=${expectedApp};
+const expectedTitle=${expectedTitle};
+const expectedBounds=${expectedBounds};
 function safeWindows(p){try{return p.windows()}catch(e){return []}}
 function safeName(spec){try{return String(spec.name()||'')}catch(e){return ''}}
+function safeProps(spec){try{return spec.properties()}catch(e){return {}}}
+function sameBounds(spec,bounds){
+  if(!bounds)return false;
+  const p=safeProps(spec),pos=Array.isArray(p.position)?p.position:[],size=Array.isArray(p.size)?p.size:[];
+  return Number(pos[0])===Number(bounds[0])&&Number(pos[1])===Number(bounds[1])&&Number(size[0])===Number(bounds[2])&&Number(size[1])===Number(bounds[3]);
+}
 function chooseProcess(){
   if(wantPid){
     const rows=se.applicationProcesses.whose({unixId:wantPid})();
-    if(rows.length)return rows[0];
+    if(rows.length){
+      if(wantApp && !safeName(rows[0]).toLowerCase().includes(wantApp.toLowerCase()))throw new Error('macOS window target app does not match the requested id/pid');
+      if(expectedApp && safeName(rows[0])!==expectedApp)throw new Error('macOS window id no longer belongs to the same application; call list_windows again');
+      return rows[0];
+    }
     throw new Error('No matching UI process found');
   }
   if(wantApp){
@@ -130,6 +241,30 @@ function chooseProcess(){
 function chooseWindow(p){
   const rows=safeWindows(p);
   if(!rows.length)throw new Error('The selected application has no accessible windows');
+  if(wantWindowIndex!==null){
+    const indexValid=Number.isInteger(wantWindowIndex)&&wantWindowIndex>=0&&wantWindowIndex<rows.length;
+    const selected=indexValid?rows[wantWindowIndex]:null;
+    if(expectedTitle){
+      if(selected&&safeName(selected)===expectedTitle)return selected;
+      const matches=[];
+      for(let i=0;i<rows.length;i++)if(safeName(rows[i])===expectedTitle)matches.push(rows[i]);
+      if(matches.length===1)return matches[0];
+      if(matches.length>1&&expectedBounds){
+        const bounded=matches.filter(row=>sameBounds(row,expectedBounds));
+        if(bounded.length===1)return bounded[0];
+      }
+      throw new Error('macOS window id no longer identifies one unambiguous window; call list_windows again');
+    }
+    if(expectedBounds){
+      if(selected&&sameBounds(selected,expectedBounds))return selected;
+      const bounded=rows.filter(row=>sameBounds(row,expectedBounds));
+      if(bounded.length===1)return bounded[0];
+      throw new Error('macOS window id no longer identifies one unambiguous window; call list_windows again');
+    }
+    if(!indexValid)throw new Error('macOS window id is stale; call list_windows again');
+    if(wantTitle && !safeName(selected).toLowerCase().includes(wantTitle.toLowerCase()))throw new Error('macOS window id no longer matches the requested title; call list_windows again');
+    return selected;
+  }
   if(wantTitle){
     for(let i=0;i<rows.length;i++){
       if(safeName(rows[i]).toLowerCase().includes(wantTitle.toLowerCase()))return rows[i];

package/src/extended/desktop.mjs

@@ -355,7 +355,11 @@ export async function uiAction(args = {}) {
   if (['set_value','set_range_value'].includes(action) && resolved.value == null) throw new Error(`ui_action ${action} requires value`);
   return adapter.uiAction(resolved);
 }
-export async function keyboard(args = {}) { return adapter.keyboard(args); }
+export async function keyboard(args = {}) {
+  const explicitWindowTarget = explicitTypeTextWindowTarget(args, false);
+  if (explicitWindowTarget) await windowAction({ action:'focus', ...explicitWindowTarget });
+  return adapter.keyboard(args);
+}
 export async function pointer(args = {}) {
   if (args.action === 'move' && ![args.x,args.y].every(value => Number.isFinite(Number(value)))) throw new Error('pointer move requires x and y');
   return adapter.pointer(args);
@@ -373,13 +377,23 @@ export async function screenshotRegion(args = {}) {
     const title = optionalString(args.title);
     const pid = Number.isInteger(Number(args.pid)) ? Number(args.pid) : null;
     if (windowId || app || title || pid != null) {
-      const rows = resultValue(await listWindows({ include_monitor:false }));
-      const row = Array.isArray(rows) ? rows.find(item =>
-        (!windowId || item.id === windowId)
-        && (pid == null || Number(item.pid) === pid)
-        && (!app || String(item.app || '').toLowerCase().includes(app.toLowerCase()))
-        && (!title || String(item.title || '').toLowerCase().includes(title.toLowerCase()))
-      ) : null;
+      let row = null;
+      if (windowId && typeof adapter.resolveWindowTarget === 'function') {
+        row = resultValue(await adapter.resolveWindowTarget({
+          id:windowId,
+          ...(pid != null ? { pid } : {}),
+          ...(app ? { app } : {}),
+          ...(title ? { title } : {}),
+        }));
+      } else {
+        const rows = resultValue(await listWindows({ include_monitor:false }));
+        row = Array.isArray(rows) ? rows.find(item =>
+          (!windowId || item.id === windowId)
+          && (pid == null || Number(item.pid) === pid)
+          && (!app || String(item.app || '').toLowerCase().includes(app.toLowerCase()))
+          && (!title || String(item.title || '').toLowerCase().includes(title.toLowerCase()))
+        ) : null;
+      }
       if (!row) throw new Error('No matching window found for screenshot_region');
       x = Number(row.x); y = Number(row.y); width = Number(row.width); height = Number(row.height);
     } else if (args.monitor != null || args.monitor_index != null) {

package/src/policy.mjs

@@ -2,10 +2,10 @@ import { runtimeConfig } from './config.mjs';
 import { recordEvent } from './telemetry.mjs';
 import { fail } from './util.mjs';
 
-// Optional hardening rules for catastrophic host-level commands. The default is `allow`:
-// ReMCP is a remote-control tool for computers you own, and the agent needs to be able to
-// do anything you could do at a shell. Deployments that want a safety net can set
-// `dangerousCommands` to `warn` (run and report) or `block` (refuse before running).
+// Built-in hardening rules for catastrophic host-level commands. The default is `block`:
+// fresh installations refuse these commands before execution. Operators can explicitly choose
+// `warn` (run and report) or `allow` (disable this built-in guardrail); unrestricted/godmode
+// also forces `allow` and remains a local-only opt-in.
 //
 // Rules are matched against the *command word* of each shell segment, so a read-only
 // command that merely mentions a dangerous word (`grep -n format README.md`,