zsh: let a machine withhold node-login-shell's execute

execute runs any command as the operator account, which can become root
without a person. The operator withholds it on the control-node until a
call needs a person's approval (hq ADR 0268); the other machines keep it
for now. The setting execute (serve by default) is written into a
root-owned file the tools bundle reads at start, and anything but serve
withholds the verb, so the machine's runtime does not offer it.

modules/zsh/shell.ts

@@ -15,7 +15,7 @@
 //   and the answer says it was cut.
 
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import { homedir, userInfo } from "node:os";
 
@@ -177,3 +177,49 @@ export async function zshFile(path: string, cap: number = OUTPUT_CAP_BYTES): Pro
     content: text.length > cap ? text.slice(0, cap) : text,
   };
 }
+
+// Whether this machine serves `execute` (novox/hq ADR 0268). The command runs as the operator account,
+// which can become root without a person, so a machine may withhold the verb: the control-node does,
+// until a call to it needs a person's approval. The choice is the module's setting `execute`, which the
+// mesh writes into a root-owned file named by the bundle's word ZSH_TOOLS_CONF; the runtime is
+// restarted when that file changes. **Anything but `serve` withholds it** — a wrong value, a missing line
+// or an unreadable file — because a verb that roots the machine is not served by accident; the reason
+// is said on stderr and in zsh_config.
+
+/** The bundle's word naming the file the machine's setting is written to. */
+export const TOOLS_CONF_WORD = "ZSH_TOOLS_CONF";
+
+export interface ExecuteSetting {
+  served: boolean;
+  why: string;
+}
+
+/** The setting as the file's text says it; undefined when there is no file to read. */
+export function executeServed(text: string | undefined): ExecuteSetting {
+  if (text === undefined) return { served: false, why: "no setting was read, so execute is withheld" };
+  let value: string | undefined;
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t || t.startsWith("#")) continue;
+    const at = t.indexOf("=");
+    if (at < 0) continue;
+    if (t.slice(0, at).trim() === "execute") value = t.slice(at + 1).trim();
+  }
+  if (value === "serve") return { served: true, why: "this machine's setting execute is serve" };
+  if (value === "withhold") return { served: false, why: "this machine's setting execute is withhold (novox/hq ADR 0268)" };
+  if (value === undefined) return { served: false, why: "the setting file says nothing of execute, so it is withheld" };
+  return { served: false, why: `the setting execute is ${JSON.stringify(value)}, neither serve nor withhold, so it is withheld` };
+}
+
+/** The setting as this machine's file says it, read once when the bundle registers its tools. */
+export function readExecuteSetting(env: NodeJS.ProcessEnv): ExecuteSetting {
+  const path = env[TOOLS_CONF_WORD]?.trim();
+  if (!path) return { served: false, why: `no ${TOOLS_CONF_WORD} names the setting file, so execute is withheld` };
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (err) {
+    return { served: false, why: `cannot read ${path} (${(err as Error).message}), so execute is withheld` };
+  }
+  return executeServed(text);
+}