@mmerterden/multi-agent-pipeline 20.30.0 → 20.34.0

package/pipeline/scripts/office-control.mjs

@@ -6,7 +6,7 @@
  *
  *   on [--no-open]   start contract-server.mjs in the background with the
  *                    installed panel page (../office/index.html, passed as
- *                    MA_OFFICE_PAGE) and an 8 hour lifetime, or reuse the one this script
+ *                    MA_OFFICE_PAGE), running until `off`, or reuse the one this script
  *                    started if it is still alive, then open the browser at
  *                    /office with a one-time code in the URL fragment,
  *                    through a 0600 launcher file so the code is never on a
@@ -30,8 +30,8 @@
  *                    script only reports it; it carries no remote code.
  *
  * State: one 0600 file, ~/.claude/logs/multi-agent/office/office.json, with
- * the pid, port and token file of the server this script started. Nothing runs
- * while the panel is closed: the server exits by itself after its idle time.
+ * the pid, port and token file of the server this script started. The server
+ * runs until office-off stops it; no daemon, hook or watcher runs beside it.
  *
  * Usage:
  *   office-control.mjs on [--no-open] [--json]
@@ -56,11 +56,16 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+
+import { codeDigest } from "../lib/code-digest.mjs";
 import { fileURLToPath } from "node:url";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
-const IDLE_MINUTES = 15;
-const MAX_HOURS = 8;
+// The panel runs until office-off: no idle stop and no lifetime, because a
+// person keeps it open beside their work. The server still binds 127.0.0.1
+// only, and every office-on that starts one mints a new token.
+const IDLE_MINUTES = 0;
+const MAX_HOURS = 0;
 /** How far a process's start may sit before its token file's startedAt. */
 const START_SKEW_MS = 120 * 1000;
 
@@ -248,10 +253,23 @@ function openBrowser(target, env) {
   return r.status === 0;
 }
 
-/** Start (or reuse) the panel server and open the browser. */
+const digestOf = (server) => (server ? codeDigest(dirname(server)) : null);
+
+/**
+ * Start (or reuse) the panel server and open the browser. A running server
+ * whose code on disk has changed since it started (an update installed a new
+ * pipeline) is stopped and a new one started, so the panel never runs on a
+ * server older than its page.
+ */
 export async function officeOn({ env = process.env, open = true } = {}) {
   let s = current(env);
   let reused = true;
+  let restarted = false;
+  if (s && s.serverDigest && s.serverDigest !== digestOf(serverScript(env))) {
+    officeOff({ env });
+    s = null;
+    restarted = true;
+  }
   if (!s) {
     reused = false;
     const server = serverScript(env);
@@ -289,13 +307,22 @@ export async function officeOn({ env = process.env, open = true } = {}) {
       idleMinutes: info.idleMinutes,
       maxHours: info.maxHours ?? null,
       startedAt: new Date().toISOString(),
+      serverDigest: digestOf(server),
     });
     s = current(env);
     if (!s) throw new Error("the server stopped right after it started");
   }
   const page = `${s.url}/office`;
   const opened = open ? openBrowser(`${page}#code=${await panelCode(s)}`, env) : false;
-  return { running: true, reused, url: page, pid: s.pid, idleMinutes: s.idleMinutes, opened };
+  return {
+    running: true,
+    reused,
+    restarted,
+    url: page,
+    pid: s.pid,
+    idleMinutes: s.idleMinutes,
+    opened,
+  };
 }
 
 /** Stop the server this script started. */

package/pipeline/scripts/office-credentials.mjs

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+/**
+ * @file office-credentials.mjs  -  the key cabinet: which services the pipeline
+ * holds a credential for and whether each one works, never a value.
+ *
+ * The answer comes from lib/credential-inventory.sh, the same inventory a run
+ * consults before asking the user for data an external system holds. That
+ * script probes a credential through the credential store with stdout
+ * discarded, so a secret never reaches this process; this file keeps only the
+ * logical name, the state, the probe verdict and what the credential is for,
+ * each checked against a fixed vocabulary.
+ *
+ * Renewing a credential stays in the terminal (`/multi-agent:setup`): the
+ * secret never passes through the browser.
+ *
+ * Usage:
+ *   office-credentials.mjs [--json] [--probe]
+ *
+ * Exit: 0 printed, 2 usage.
+ *
+ * @module pipeline/scripts/office-credentials
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const HERE = dirname(fileURLToPath(import.meta.url));
+const STATES = new Set(["present", "mapped-but-missing", "unmapped"]);
+const REACH = new Set([
+  "not-probed",
+  "reachable",
+  "auth-rejected",
+  "unreachable",
+  "no-host-configured",
+  "well-formed",
+  "not-probeable",
+  "malformed",
+  "no-credential",
+  "probe-error",
+  "server-error",
+  "tier-1-ready",
+  "tier-2-ready",
+  "tier-1-no-grant",
+]);
+const NAME = /^[a-z][a-z0-9_]{0,60}$/;
+
+function inventoryPath(env) {
+  if (env.MA_CREDENTIAL_INVENTORY) return env.MA_CREDENTIAL_INVENTORY;
+  for (const p of [join(HERE, "..", "lib", "credential-inventory.sh")]) if (existsSync(p)) return p;
+  return null;
+}
+
+export async function officeCredentials({ probe = false, env = process.env } = {}) {
+  const script = inventoryPath(env);
+  const base = {
+    contractVersion: CONTRACT_VERSION,
+    generatedAt: new Date().toISOString(),
+    probed: probe,
+  };
+  if (!script) return { ...base, available: false, credentials: [] };
+  const r = await spawnAsync("bash", [script, "--json", ...(probe ? ["--probe"] : [])], {
+    env,
+    timeoutMs: probe ? 45000 : 10000,
+  });
+  const doc = (() => {
+    try {
+      return JSON.parse(r.stdout || "");
+    } catch {
+      return null;
+    }
+  })();
+  const rows = Array.isArray(doc?.credentials) ? doc.credentials : [];
+  return {
+    ...base,
+    available: Boolean(doc),
+    credentials: rows
+      .filter((c) => typeof c?.logical === "string" && NAME.test(c.logical))
+      .map((c) => ({
+        logical: c.logical,
+        state: STATES.has(c.state) ? c.state : "mapped-but-missing",
+        // A verdict this file does not know is reported as unknown, never as
+        // not checked: a probe that ran said something.
+        reachability: REACH.has(c.reachability) ? c.reachability : probe ? "unknown" : "not-probed",
+        capability: typeof c.capability === "string" ? c.capability.slice(0, 160) : null,
+      })),
+  };
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.some((a) => a !== "--json" && a !== "--probe")) {
+    console.error("usage: office-credentials.mjs [--json] [--probe]");
+    process.exit(2);
+  }
+  const doc = await officeCredentials({ probe: args.includes("--probe") });
+  process.stdout.write(
+    args.includes("--json")
+      ? JSON.stringify(doc) + "\n"
+      : doc.credentials.map((c) => `${c.logical}: ${c.state}, ${c.reachability}`).join("\n") + "\n",
+  );
+}

package/pipeline/scripts/office-memory.mjs

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+/**
+ * @file office-memory.mjs  -  what the pipeline has learned, per repository.
+ *
+ * The learning loop writes four stores, and this reads them without changing
+ * any:
+ *
+ *   code graph      ~/.claude/knowledge/<repo>/code-graph.json (graph-build.mjs)
+ *   learnings       ~/.claude/memory/multi-agent/<repo>/learnings-ledger.jsonl
+ *                   (learnings-ledger.mjs: durable facts, conventions, rejected
+ *                   preferences replayed into later runs)
+ *   past findings   .../triage-corpus.jsonl (triage-memory.mjs: review findings)
+ *   session notes   .../session-notes.jsonl (learn-from-transcripts.mjs)
+ *
+ * For each repository: when the graph was built and how large it is, how many
+ * learnings, findings and session notes there are, the newest learnings'
+ * statements (redacted and cut short) and when anything was last written. An
+ * empty shelf is reported as empty, so a repository the loop never fed shows.
+ *
+ * Usage:
+ *   office-memory.mjs [--json]
+ *
+ * MA_MEMORY_ROOT and MA_KNOWLEDGE_ROOT override the two roots. Each store is
+ * read asynchronously: lines are counted in chunks and only the last
+ * MAX_BYTES are parsed, so a store that keeps growing never blocks the server.
+ *
+ * Exit: 0 printed, 2 usage.
+ *
+ * @module pipeline/scripts/office-memory
+ */
+
+import { constants, createReadStream, existsSync, readdirSync, statSync } from "node:fs";
+import { open } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { createRedactor } from "./transcript-index.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+const MAX_REPOS = 60;
+const RECENT = 5;
+const REPO = /^[A-Za-z0-9._-]{1,100}$/;
+const MAX_BYTES = 1024 * 1024;
+
+const roots = (env) => ({
+  memory: env.MA_MEMORY_ROOT || join(homedir(), ".claude", "memory", "multi-agent"),
+  knowledge: env.MA_KNOWLEDGE_ROOT || join(homedir(), ".claude", "knowledge"),
+});
+
+const dirsOf = (root) => {
+  try {
+    return readdirSync(root, { withFileTypes: true })
+      .filter((d) => d.isDirectory() && REPO.test(d.name))
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+};
+
+// A line that is not a JSON object is skipped like an unreadable one.
+const parse = (line) => {
+  try {
+    const v = JSON.parse(line);
+    return v && typeof v === "object" && !Array.isArray(v) ? [v] : [];
+  } catch {
+    return [];
+  }
+};
+
+// A store's lines, the same way for a small file read whole and a large one
+// counted in chunks: every newline, and a last line that has none.
+function linesIn(buf) {
+  let n = 0;
+  for (let i = buf.indexOf(10); i !== -1; i = buf.indexOf(10, i + 1)) n++;
+  return n + (buf.length && buf[buf.length - 1] !== 10 ? 1 : 0);
+}
+
+// Counted through the handle already open, so the count is of the same file.
+async function countLines(fh, size) {
+  let n = 0;
+  let last = 10;
+  const stream = createReadStream(null, { fd: fh.fd, start: 0, end: size - 1, autoClose: false });
+  for await (const chunk of stream) {
+    for (let i = chunk.indexOf(10); i !== -1; i = chunk.indexOf(10, i + 1)) n++;
+    if (chunk.length) last = chunk[chunk.length - 1];
+  }
+  return n + (size > 0 && last !== 10 ? 1 : 0);
+}
+
+/**
+ * A store's line count and its last lines parsed (unreadable lines skipped);
+ * { count: 0, tail: [] } for no file. Only the last `maxBytes` are parsed.
+ */
+async function store(path, maxBytes) {
+  let fh;
+  try {
+    // Non-blocking and not through a link: a FIFO or a symlink planted in a
+    // store's place is skipped instead of holding a worker thread.
+    fh = await open(path, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW);
+    const st = await fh.stat();
+    if (!st.isFile()) return { count: 0, tail: [] };
+    const { size } = st;
+    const start = Math.max(0, size - maxBytes);
+    const buf = Buffer.alloc(size - start);
+    await fh.read(buf, 0, buf.length, start);
+    let text = buf.toString("utf8");
+    if (start > 0) text = text.slice(text.indexOf("\n") + 1);
+    const lines = text.split("\n").filter(Boolean);
+    const count = start > 0 ? await countLines(fh, size) : linesIn(buf);
+    return { count, tail: lines.flatMap(parse) };
+  } catch {
+    return { count: 0, tail: [] };
+  } finally {
+    await fh?.close();
+  }
+}
+
+const ms = (v) => {
+  const t = Date.parse(v ?? "");
+  return Number.isFinite(t) ? t : null;
+};
+const iso = (t) => (t === null ? null : new Date(t).toISOString());
+
+async function shelf(name, r, now, R, maxBytes) {
+  const dir = join(r.memory, name);
+  const graphPath = join(r.knowledge, name, "code-graph.json");
+  let graph = null;
+  if (existsSync(graphPath)) {
+    const st = statSync(graphPath);
+    graph = {
+      builtAt: iso(st.mtimeMs),
+      ageDays: Math.max(0, Math.floor((now - st.mtimeMs) / 86_400_000)),
+      sizeKb: Math.round(st.size / 1024),
+    };
+  }
+  const [learnings, findings, notes] = await Promise.all(
+    ["learnings-ledger.jsonl", "triage-corpus.jsonl", "session-notes.jsonl"].map((f) =>
+      store(join(dir, f), maxBytes),
+    ),
+  );
+  const times = [...learnings.tail, ...findings.tail, ...notes.tail]
+    .map((x) => ms(x.ts))
+    .filter((t) => t !== null);
+  if (graph) times.push(ms(graph.builtAt));
+  return {
+    repo: name,
+    graph,
+    learnings: learnings.count,
+    findings: findings.count,
+    sessionNotes: notes.count,
+    recent: learnings.tail
+      .slice(-RECENT)
+      .reverse()
+      .map((x) => ({
+        kind: typeof x.kind === "string" ? x.kind.slice(0, 30) : null,
+        statement: R.excerpt(String(x.statement ?? ""), 120) ?? "",
+        at: iso(ms(x.ts)),
+      })),
+    lastWrite: times.length ? iso(Math.max(...times)) : null,
+  };
+}
+
+export async function officeMemory({
+  env = process.env,
+  now = Date.now(),
+  maxBytes = MAX_BYTES,
+} = {}) {
+  const r = roots(env);
+  // The transcript redactor: credentials by provider rule as well as paths
+  // and addresses, the same pass the activity view uses.
+  const R = createRedactor();
+  const names = [...new Set([...dirsOf(r.memory), ...dirsOf(r.knowledge)])];
+  // One shelf that cannot be read is left out; the others still answer.
+  const read = await Promise.all(names.map((n) => shelf(n, r, now, R, maxBytes).catch(() => null)));
+  const shelves = read
+    .filter(Boolean)
+    .sort((a, b) => (b.lastWrite ?? "").localeCompare(a.lastWrite ?? ""))
+    .slice(0, MAX_REPOS);
+  return { contractVersion: CONTRACT_VERSION, generatedAt: new Date(now).toISOString(), shelves };
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.some((a) => a !== "--json")) {
+    console.error("usage: office-memory.mjs [--json]");
+    process.exit(2);
+  }
+  const doc = await officeMemory();
+  process.stdout.write(
+    args.includes("--json")
+      ? JSON.stringify(doc) + "\n"
+      : doc.shelves
+          .map(
+            (s) =>
+              `${s.repo}: graph ${s.graph ? s.graph.ageDays + "d old" : "none"}, ${s.learnings} learnings, ${s.findings} findings, ${s.sessionNotes} notes`,
+          )
+          .join("\n") + "\n",
+  );
+}

package/pipeline/scripts/office-prune.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * @file office-prune.mjs  -  old run logs, cleared from the restroom.
+ *
+ * A thin wrapper over prune-logs.sh, the same script /multi-agent:prune-logs
+ * runs: its dry run is the preview (which task log folders would go and the
+ * space freed). On the office's route (pruneApply) the confirmed step lists
+ * the folders again, refuses with code "changed" when they differ from the
+ * preview, and then prunes only that list (prune-logs.sh --only-from); the
+ * CLI's `apply` prunes the age directly, as /multi-agent:prune-logs does.
+ * Everything prune-logs.sh guarantees holds here: the audit trail,
+ * the metrics corpus and the task counters are never touched, the log root is
+ * refused when it is /, the home folder or a git checkout, a folder written
+ * in the last minutes is spared so a live run keeps its log, and so is a run
+ * that can still be resumed.
+ *
+ * The age is one of a fixed set of days; nothing else reaches the script.
+ *
+ * Usage:
+ *   office-prune.mjs preview <days> [--json]
+ *   office-prune.mjs apply <days> [--json]
+ *
+ * PRUNE_LOG_ROOT overrides the log root, as for prune-logs.sh.
+ *
+ * Exit: 0 printed, 1 prune-logs.sh refused, 2 usage.
+ *
+ * @module pipeline/scripts/office-prune
+ */
+
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const AGES = [7, 30, 90];
+const HERE = dirname(fileURLToPath(import.meta.url));
+const MAX_LISTED = 200;
+
+/** What a prune-logs.sh run printed: the folders and the space freed. */
+export function parsePrune(text) {
+  const lines = String(text).split("\n");
+  const head = lines.find((l) => /would remove|removed/i.test(l)) || "";
+  const removed = /removed (\d+)\/\d+ task log dir/.exec(head);
+  const n = Number(removed ? removed[1] : ((/(\d+) task log dir/.exec(head) || [])[1] ?? 0));
+  const size = /~(\d+(?:\.\d+)?) ?(KB|MB)/.exec(head);
+  const mb = size
+    ? size[2] === "KB"
+      ? Math.round((Number(size[1]) / 1024) * 10) / 10
+      : Number(size[1])
+    : 0;
+  const all = lines
+    .map((l) => /^\s{2}(\S(?:.*\S)?)\s*$/.exec(l))
+    .filter(Boolean)
+    .map((m) => m[1]);
+  return { count: n || all.length, freedMb: mb, folders: all.slice(0, MAX_LISTED), all };
+}
+
+// The page sees at most MAX_LISTED folders; the confirmation compares the
+// whole list.
+async function run(days, apply, env, { keepAll = false, only = null } = {}) {
+  if (!AGES.includes(days)) throw new Error(`age must be one of ${AGES.join(", ")}`);
+  const dir = only ? mkdtempSync(join(tmpdir(), "office-prune-")) : null;
+  const list = dir ? join(dir, "only.txt") : null;
+  if (list) writeFileSync(list, only.join("\n") + "\n", { mode: 0o600 });
+  const r = await spawnAsync(
+    "bash",
+    [
+      join(HERE, "prune-logs.sh"),
+      `--older-than=${days}`,
+      ...(list ? [`--only-from=${list}`] : []),
+      ...(apply ? ["--yes"] : []),
+    ],
+    { env, timeoutMs: 120_000 },
+  ).finally(() => dir && rmSync(dir, { recursive: true, force: true }));
+  if (r.status !== 0) throw new Error("prune-logs.sh refused (exit " + r.status + ")");
+  const { all, ...parsed } = parsePrune(r.stdout);
+  return {
+    contractVersion: CONTRACT_VERSION,
+    olderThanDays: days,
+    applied: apply,
+    ...parsed,
+    ...(keepAll ? { all } : {}),
+  };
+}
+
+export const prunePreview = (days, env = process.env, opts = {}) => run(days, false, env, opts);
+
+/**
+ * Prunes only what the preview showed: the folders are listed again and the
+ * prune runs only when they are the same set, and then only on that list, so
+ * a run that aged into the window or a folder that appeared since is never
+ * removed unseen.
+ */
+export async function pruneApply(days, env = process.env, expected = null) {
+  if (expected && Array.isArray(expected.all)) {
+    const now = await run(days, false, env, { keepAll: true });
+    const want = new Set(expected.all);
+    const same =
+      now.count === expected.count &&
+      now.all.length === want.size &&
+      now.all.every((f) => want.has(f));
+    if (!same) {
+      const e = new Error("the folders changed since the preview; preview again");
+      e.code = "changed";
+      throw e;
+    }
+    return run(days, true, env, { only: expected.all });
+  }
+  return run(days, true, env);
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const [cmd, d, flag] = process.argv.slice(2);
+  const days = Number(d);
+  if (!["preview", "apply"].includes(cmd) || !AGES.includes(days) || (flag && flag !== "--json")) {
+    console.error(`usage: office-prune.mjs preview|apply <${AGES.join("|")}> [--json]`);
+    process.exit(2);
+  }
+  const doc = await run(days, cmd === "apply", process.env);
+  process.stdout.write(JSON.stringify(doc) + "\n");
+}

package/pipeline/scripts/office-settings.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+/**
+ * @file office-settings.mjs  -  the three switches the office can flip, read
+ * and changed through the same code the terminal commands use.
+ *
+ *   language  prefs.global.outputLanguage, en or tr, as /multi-agent:language
+ *             writes it (promptLanguage forced back to en in the same write),
+ *             then localize-commands.mjs swaps the installed picker text
+ *   model     the fable rung, through lib/model-rung.sh on|off
+ *   route     model routing, through lib/route-state.sh on|off; `on` keeps
+ *             the saved configuration, and anything that would widen it (a
+ *             free provider, new rules) stays in the terminal
+ *
+ * Every value is one of a fixed set; nothing else reaches a script.
+ *
+ * Usage:
+ *   office-settings.mjs [--json]
+ *   office-settings.mjs set <language|model|route> <value> [--json]
+ *
+ * MULTI_AGENT_PREFS overrides the preferences file, as for the scripts it calls.
+ *
+ * Exit: 0 printed or applied, 1 the change failed, 2 usage.
+ *
+ * @module pipeline/scripts/office-settings
+ */
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+import { updateJsonFileSync } from "../lib/json-file-lock.mjs";
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { spawnAsync } from "./_spawn-async.mjs";
+
+export const CONTRACT_VERSION = "1.0.0";
+export const CHOICES = {
+  language: ["en", "tr"],
+  model: ["on", "off"],
+  route: ["on", "off"],
+};
+const STRATEGIES = ["manual", "task-fit", "cost-ceiling"];
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+const prefsPath = (env) =>
+  env.MULTI_AGENT_PREFS || join(env.HOME || homedir(), ".claude", "multi-agent-preferences.json");
+
+function libScript(name) {
+  const p = join(HERE, "..", "lib", name);
+  return existsSync(p) ? p : null;
+}
+
+/** What the switches are set to now. */
+export function readSettings(env = process.env) {
+  const g = readRegularJson(prefsPath(env), {})?.global ?? {};
+  return {
+    contractVersion: CONTRACT_VERSION,
+    language: g.outputLanguage === "tr" ? "tr" : "en",
+    model: g.modelFallback?.fableEnabled === true ? "on" : "off",
+    route: g.modelRouting?.enabled === true ? "on" : "off",
+  };
+}
+
+/**
+ * The free provider chain a saved routing configuration keeps across `route
+ * off`, which `route on` brings back; null when none is saved.
+ */
+export function freeChainOf(env = process.env) {
+  const free = readRegularJson(prefsPath(env), {})?.global?.modelRouting?.free;
+  if (free?.enabled !== true) return null;
+  return { enabled: true, allowTraining: free.allowTraining === true };
+}
+
+export class SettingsError extends Error {}
+
+// route-state.sh on resets the strategy to manual unless told otherwise; the
+// saved one is passed back so `on` changes only the switch.
+function routeArgs(setting, value, env) {
+  if (setting !== "route" || value !== "on") return [];
+  const saved = readRegularJson(prefsPath(env), {})?.global?.modelRouting?.strategy;
+  return [`--strategy=${STRATEGIES.includes(saved) ? saved : "manual"}`];
+}
+
+/** Flip one switch to one of its values; returns the settings afterwards. */
+export async function applySetting(setting, value, env = process.env) {
+  if (!CHOICES[setting]?.includes(value)) throw new SettingsError(`${setting}: not a choice`);
+  if (setting === "language") {
+    const path = prefsPath(env);
+    if (!existsSync(path)) throw new SettingsError("no preferences file");
+    let written = false;
+    updateJsonFileSync(path, (cur) => {
+      if (!cur || typeof cur !== "object" || Array.isArray(cur)) return undefined;
+      written = true;
+      const global = { ...(cur.global ?? {}), promptLanguage: "en", outputLanguage: value };
+      return { ...cur, global };
+    });
+    if (!written)
+      throw new SettingsError("language: the preferences file is not an object, not written");
+    const loc = join(HERE, "localize-commands.mjs");
+    if (existsSync(loc)) {
+      const r = await spawnAsync(process.execPath, [loc, value === "tr" ? "apply" : "restore"], {
+        env,
+        timeoutMs: 30_000,
+      });
+      if (r.status !== 0)
+        throw new SettingsError(
+          `language: saved, but the command descriptions were not switched (exit ${r.status})`,
+        );
+    }
+  } else {
+    const script = libScript(setting === "model" ? "model-rung.sh" : "route-state.sh");
+    if (!script) throw new SettingsError(`${setting}: script not installed`);
+    const r = await spawnAsync("bash", [script, value, ...routeArgs(setting, value, env)], {
+      env,
+      timeoutMs: 30_000,
+    });
+    if (r.status !== 0)
+      throw new SettingsError(`${setting}: the script refused (exit ${r.status})`);
+  }
+  return readSettings(env);
+}
+
+if (invokedDirectly(import.meta.url)) {
+  const args = process.argv.slice(2).filter((a) => a !== "--json");
+  const json = process.argv.includes("--json");
+  const out = (doc) =>
+    process.stdout.write(
+      json
+        ? JSON.stringify(doc) + "\n"
+        : `language ${doc.language}, model ${doc.model}, route ${doc.route}\n`,
+    );
+  if (!args.length) out(readSettings());
+  else if (args[0] === "set" && args.length === 3) {
+    try {
+      out(await applySetting(args[1], args[2]));
+    } catch (e) {
+      console.error(String(e.message));
+      process.exit(1);
+    }
+  } else {
+    console.error("usage: office-settings.mjs [set <language|model|route> <value>] [--json]");
+    process.exit(2);
+  }
+}