seisin 0.6.4 → 0.7.0

package/src/sandboxes/index.js

@@ -3,8 +3,9 @@
  *
  * seisin decides the policy; a sandbox enforces it. There are three ways in:
  *
- *   - `srt` (built in, the default): @anthropic-ai/sandbox-runtime;
- *   - `tartaros` (built in): reads the settings file itself (`--settings`);
+ *   - `tartaros` (built in, the default, installed with seisin): reads the
+ *     settings file itself (`--settings`);
+ *   - `srt` (built in, installed apart): @anthropic-ai/sandbox-runtime;
  *   - any name declared under `[sandbox.providers.<name>]`: a command that
  *     takes the settings file (command.js, docs/sandboxes.md).
  *
@@ -23,17 +24,25 @@
 import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { srt } from "./srt.js";
+import { srt, SRT_PACKAGE, SRT_VERSION } from "./srt.js";
 import { machOf } from "../browsers.js";
 import { tartaros } from "./tartaros.js";
 import { commandSandbox } from "./command.js";
 
 export const BUILTIN_SANDBOXES = { srt, tartaros };
-export const DEFAULT_SANDBOX = "srt";
+export const DEFAULT_SANDBOX = "tartaros";
+/**
+ * Without `[sandbox] provider`: tartaros, which installs with seisin, then srt
+ * where it is installed apart (it is not a dependency since 0.7). A role
+ * tartaros cannot hold (a blanket local binding, a host's missing Landlock)
+ * runs under srt if it is there and holds all of it, and otherwise does not
+ * run, with what each one lacked.
+ */
+export const DEFAULT_PROVIDERS = [DEFAULT_SANDBOX, "srt"];
 
 /** The sandboxes the config names, in its order, as provider objects. */
 export function sandboxesOf(config) {
-  const names = config.sandbox?.provider ?? [DEFAULT_SANDBOX];
+  const names = config.sandbox?.provider ?? DEFAULT_PROVIDERS;
   return names.map((n) => BUILTIN_SANDBOXES[n] ?? commandSandbox(n, config.sandbox.providers[n].command, config.sandbox.providers[n].check, { tagsDenials: config.sandbox.providers[n].tagsDenials }));
 }
 
@@ -91,7 +100,15 @@ export function weigh(config, settings, { platform = process.platform, role = nu
       const ruled = requests.length && !sandbox.requestRules
         ? [`requests (${requests.map((q) => q.host).join(", ")}): ${sandbox.name} cannot limit the methods and paths of a host from its settings, tartaros can`]
         : [];
-      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser, ...exemption, ...ruled], warnings, missing: bin ? null : sandbox.missing() };
+      // `control_files`: a family the policy hands a role that this sandbox
+      // protects whatever the settings say (tartaros's trust-handoff set holds
+      // `.vscode` at any depth), so the role could not do what it was given.
+      const families = role ? (config.roles?.[role]?.controlFiles ?? []) : [];
+      const kept = families.filter((f) => (sandbox.keepsControlFiles ?? []).includes(f));
+      const control = kept.length
+        ? [`control_files (${kept.join(", ")}): ${sandbox.name} protects those files at any depth whatever the policy says, so the role could not edit them`]
+        : [];
+      return { sandbox, bin, unmet: [...(masking ? [masking] : []), ...unmet, ...browser, ...exemption, ...ruled, ...control], warnings, missing: bin ? null : sandbox.missing() };
     });
     const chosen = options.find((o) => o.bin && o.unmet.length === 0) ?? null;
     return { chosen, options };
@@ -114,7 +131,7 @@ export function chooseSandbox(config, settings, { platform = process.platform, r
   const { chosen, options } = weigh(config, settings, { platform, role, file });
   if (chosen) return { sandbox: chosen.sandbox, bin: chosen.bin, options };
   // The one sandbox there is, missing: said exactly as it always was.
-  if (options.length === 1 && options[0].missing && options[0].sandbox.name === DEFAULT_SANDBOX)
+  if (options.length === 1 && options[0].missing)
     return { error: new Error(options[0].missing), options };
   return { error: new Error(refusal(role, options)), options };
 }
@@ -125,6 +142,6 @@ export function refusal(role, options) {
     : `  - ${o.sandbox.name} cannot enforce all of it:\n${o.unmet.map((u) => `      ${u}`).join("\n")}`);
   return `no sandbox in [sandbox] provider can hold ${role ? `role ${role}` : "this role"} as its policy is written, so it was not started:\n` +
     `${lines.join("\n")}\n` +
-    `  A sandbox that enforces less than the policy is never used in its place. Add one that can (provider = [..., "srt"]), ` +
-    `or change the role.`;
+    `  A sandbox that enforces less than the policy is never used in its place. Install one that can ` +
+    `(srt: npm install -g ${SRT_PACKAGE}@${SRT_VERSION}), name it in [sandbox] provider, or change the role.`;
 }

package/src/sandboxes/srt.js

@@ -1,10 +1,15 @@
 /**
  * `srt`: @anthropic-ai/sandbox-runtime, the sandbox seisin was built on.
  *
- * The default, and the reference every other provider is measured against:
- * the settings seisin generates (srt.js, one level up) ARE this runtime's
- * settings file, so it enforces all of them by construction and `unmet` is
- * always empty. What a run hands it is the file and the command, nothing else.
+ * The reference every other provider is measured against: the settings seisin
+ * generates (srt-settings.js, one level up) ARE this runtime's settings file, so
+ * it enforces all of them by construction and `unmet` is always empty. What a
+ * run hands it is the file and the command, nothing else.
+ *
+ * Not a dependency since 0.7: tartaros is the default and installs with seisin.
+ * srt is used where it is installed apart (globally, or in the project), after
+ * tartaros or where `[sandbox] provider` names it, and the version it is tested
+ * with is the one in seisin's devDependencies.
  */
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { join, dirname, delimiter } from "node:path";
@@ -47,6 +52,15 @@ export function resolveSrt({ from = HERE, path = process.env.PATH } = {}) {
 }
 
 const RUNTIME = "@anthropic-ai/sandbox-runtime";
+export const SRT_PACKAGE = RUNTIME;
+/** The srt seisin is tested with (its devDependency), for the install hint. */
+export const SRT_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(HERE, "..", "..", "package.json"), "utf8")).devDependencies?.[RUNTIME] ?? "latest";
+  } catch {
+    return "latest";
+  }
+})();
 
 /**
  * The `srt` of the sandbox-runtime that resolves from `from`, or null.
@@ -148,11 +162,17 @@ export function withMachPreload(bin, file, inner) {
 export const srt = {
   name: "srt",
   locate: () => resolveSrt(),
-  missing: () => `sandbox runtime not found. ${installHint()}`,
+  missing: () => `sandbox-runtime (srt) not found: it is not installed with seisin since 0.7. ` +
+    `Install it with: npm install -g ${RUNTIME}@${SRT_VERSION}`,
   unmet: () => [],
-  // Masked credentials: on Linux; on macOS not yet (anthropics/sandbox-runtime#593).
+  // Masked credentials: on Linux. On macOS srt masks too, but it reads the real
+  // value from its own environment, and from inside its sandbox the agent can
+  // read that environment back (measured with 0.0.81).
+  // anthropics/sandbox-runtime#593 takes the value out of there.
   masks: (platform) => platform === "linux" ? null
-    : `masked credentials (key_mode = "inject") on ${platform}: sandbox-runtime does not mask them there yet (anthropics/sandbox-runtime#593); tartaros does`,
+    : platform === "darwin"
+      ? `masked credentials (key_mode = "inject") on darwin: sandbox-runtime masks them, but holds the real value in its own environment, which the agent can read from inside the sandbox (anthropics/sandbox-runtime#593 takes it out of there); tartaros does not keep it there`
+      : `masked credentials (key_mode = "inject") on ${platform}: sandbox-runtime does not mask them there; tartaros does`,
   // `--` before the command, and it is not cosmetic. Without it the runtime's
   // own argument parser reaches into what the agent was invoked with and eats
   // anything resembling one of its flags: `claude --settings`, `claude -c`.

package/src/sandboxes/tartaros.js

@@ -28,14 +28,13 @@ export const TARTAROS_PACKAGE = "@carlostapiacl/tartaros";
 
 /**
  * The tartaros seisin depends on first, one on PATH second, and nothing third:
- * the order srt is found in (srt.js), for the same reason. A tartaros built
+ * the order srt is found in (resolveSrt in sandboxes/srt.js), for the same reason. A tartaros built
  * once and left on PATH goes on answering after the pinned one has its fixes.
  *
- * The pinned one is an optional dependency: a package per platform with the
- * binary in it, and a main package whose binaryPath() finds that one whether
+ * The pinned one is a dependency: a main package whose binaryPath() finds the
+ * binary of this platform's package (an optional dependency of its own) whether
  * npm nested it under the main package (a global install, measured) or hoisted
- * it. An install that left it out (`--omit=optional`, a platform without a
- * binary) falls through to PATH.
+ * it. A platform without a binary, or `--omit=optional`, falls through to PATH.
  */
 export function resolveTartaros({ from = HERE, path = process.env.PATH } = {}) {
   const pinned = dependencyTartaros(from);
@@ -116,7 +115,10 @@ export function tartarosSettings(settings, { machRegister = [], handoffExempt =
 export const tartaros = {
   name: "tartaros",
   locate: () => resolveTartaros(),
-  missing: () => `tartaros not found: neither ${TARTAROS_PACKAGE}, which installs with seisin unless optional dependencies are left out, nor tartaros on PATH.`,
+  missing: () => `tartaros not found: neither ${TARTAROS_PACKAGE}, which installs with seisin (it has no binary for ${process.platform}-${process.arch}), nor tartaros on PATH.`,
+  // Its trust-handoff set holds the editors' folders (`.vscode`, `.idea`) at any
+  // depth, whatever the settings say: a role given them cannot edit them here.
+  keepsControlFiles: ["ide"],
   asksFile: true,
   // Masked credentials: tartaros says whether it masks them, through explain
   // (0.1.0-alpha.16 and later do; earlier ones refuse the field).

package/src/serve.js

@@ -16,10 +16,11 @@ import { readFileSync, existsSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadConfig } from "./config.js";
+import { decideRequest } from "./decide-request.js";
 import { read, logPath, logSegments } from "./log.js";
-import { settingsFor } from "./srt.js";
+import { settingsFor } from "./srt-settings.js";
 import { describeHandoff } from "./handoff.js";
-import { pending, requestsPath, settle, applyGrant, refuseIfBarred, editPolicy, cleanReason, asFileGrant, lastAgentOf, fileOnlyNote } from "./requests.js";
+import { pending, requestsPath, editPolicy, settle, cleanReason, lastAgentOf, fileOnlyNote } from "./requests.js";
 import { causesOf, describeWalls, parseSince, queue, verdicts, wallsByRole } from "./views.js";
 import { planEdit, hashOf } from "./controls.js";
 import { inspect } from "./inspect.js";
@@ -263,29 +264,17 @@ function decide(configPath, { key, decision, reason, scope = "folder" }) {
   const cfg = loadConfig(configPath);
   const file = requestsPath(cfg.root);
 
-  /**
-   * Looked up, applied and settled under one lock — the policy's, the one
-   * every grant takes (editPolicy). The lookup used to happen before it and
-   * the settle after it, so the console and `seisin grant` could both find the
-   * same request pending and both act on it. A decline takes the lock as well,
-   * though it writes no policy, for the same reason.
-   *
-   * The config is edited as text, so comments and order survive, and it is
-   * written before the queue is settled: if the write throws, the request is
-   * still open rather than marked done against a file that never changed.
-   */
   let req = null;
   let result = null;
   try {
-    result = editPolicy(cfg, (before) => {
-      const current = loadConfig(configPath, before);
-      req = pending(file, { keyDirs: current.keyDirs }).find((r) => r.key === key);
-      if (!req) throw bad(`request ${key} is no longer pending — reload to see the queue as it is now`);
-      if (decision !== "granted") return { toml: before, changed: false };
-      if (scope === "file") req = asFileGrant(req);
-      refuseIfBarred(current, req);
-      return applyGrant(before, req, reason);
-    }, { after: () => settle(file, req.key, decision, reason, { only: req.only }) });
+    ({ request: req, ...result } = decideRequest(cfg, {
+      decision, reason, only: scope === "file",
+      select: (current) => {
+        const request = pending(file, { keyDirs: current.keyDirs }).find((r) => r.key === key);
+        if (!request) throw bad(`request ${key} is no longer pending — reload to see the queue as it is now`);
+        return request;
+      },
+    }));
   } catch (e) {
     if (e.code === "ELOCKED") throw Object.assign(new Error("another grant is in progress — try again in a moment"), { status: 503 });
     throw e;

package/src/spool.js

@@ -7,7 +7,7 @@
  * request queue writable by the process they are a record of: an agent could
  * truncate `log.jsonl`, rewrite a decision, or invent a request that had never
  * been refused. The files said "append-only" in their own comments and nothing
- * enforced it. An external review named this and was right.
+ * enforced it. A review named this and was right.
  *
  * So the file moves out of reach and a socket takes its place:
  *

package/src/{srt.js → srt-settings.js}

@@ -33,7 +33,7 @@ import {
   CREDENTIAL_HOMES, toWritePath, writePathsOf, otherAgentsCredentials,
 } from "./grants.js";
 
-// Re-exported: these were srt.js's exports before grants.js existed, and
+// Re-exported: these were srt-settings.js's exports before grants.js existed, and
 // callers (the CLI, the tests, anyone embedding seisin) import them from here.
 export {
   expand, homeFits, roleHome, roleHomeRoot, CREDENTIAL_HOMES, RUNTIME_WRITES,

package/src/suggest.js

@@ -41,12 +41,37 @@ export function unknownRole(config, role) {
  * `--verbsoe` is a question answered as if it had not been asked.
  * `values` are the flags that take the next word as their value.
  */
+/**
+ * A count a person types (`--min 3`): a whole number from 1. Anything else is
+ * refused; `Number("banana")` made every comparison false and the answer
+ * "no walls" looked like a real one.
+ */
+export function positiveInt(flag, value) {
+  if (!/^[1-9][0-9]*$/.test(String(value ?? ""))) {
+    const e = new Error(`${flag} takes a whole number from 1, not "${value ?? ""}"`);
+    e.usage = true;
+    throw e;
+  }
+  return Number(value);
+}
+
 export function checkFlags(command, argv, known, values = []) {
   const all = [...known, ...values];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--") break;
-    if (values.includes(a)) { i++; continue; }
+    if (values.includes(a)) {
+      // A flag that takes a value and has none is refused: `log --role` read
+      // as no filter at all, and answered for every role.
+      const v = argv[i + 1];
+      if (v === undefined || v === "--" || (v.startsWith("-") && v !== "-")) {
+        const e = new Error(`${a} needs a value\n  seisin ${command} --help lists its flags`);
+        e.usage = true;
+        throw e;
+      }
+      i++;
+      continue;
+    }
     if (!a.startsWith("-") || a === "-") continue;
     if (all.includes(a)) continue;
     const near = nearest(a, all);

package/src/territory.js

@@ -50,7 +50,7 @@
  * nothing else in a data root is.
  */
 import { readdirSync, lstatSync } from "node:fs";
-import { homedir, tmpdir } from "node:os";
+import { homedir, tmpdir, userInfo } from "node:os";
 import { realOrSelf, writePathsOf, expand } from "./grants.js";
 import { realAncestor } from "./paths.js";
 
@@ -64,9 +64,19 @@ export const AGENT_FILES = { claude: ["~/.claude.json"], codex: [] };
  * and that hold nothing about anybody. On macOS CoreFoundation reads
  * `~/.CFUserTextEncoding` (a text-encoding code, `0x1F5:0x0:0x0`); shut, it was
  * 278 of 409 denials in one orchestrator's runs, every one of them noise.
+ * The system reads it from the account's home, not from `$HOME`: an
+ * orchestrator that gives each run its own HOME still sees the real file read
+ * (measured), so these resolve against the account, see `accountHome`.
  */
 export const PLATFORM_FILES = { darwin: ["~/.CFUserTextEncoding"], linux: [] };
 
+/** The home directory of the account, from the user database, whatever `$HOME` says. */
+export function accountHome() {
+  try { return userInfo().homedir || homedir(); } catch { return homedir(); }
+}
+
+const expandAccount = (p) => (p.startsWith("~/") ? `${accountHome()}/${p.slice(2)}` : expand(p));
+
 /**
  * Where data lives, per platform. Whole roots: what is under them belongs to
  * somebody. `/opt/homebrew/var` and `/usr/local/var` hold the databases a
@@ -233,7 +243,7 @@ export function keptFor(config, role, { observe = false, agent, program } = {})
     // starts and says "Not logged in" (measured, 2026-10-09). A run of no
     // agent, or of another, does not get it.
     ...(agent ? (AGENT_FILES[agent] ?? []).map(expand) : []),
-    ...(PLATFORM_FILES[process.platform] ?? []).map(expand),
+    ...(PLATFORM_FILES[process.platform] ?? []).map(expandAccount),
     ...writePathsOf(config, role, { observe, agent }),
     ...(role.reads ?? []).map((p) => readPath(config.root, p)),
     ...(role.toolchain ?? []).map((p) => readPath(config.root, p)),

package/src/toml.js

@@ -0,0 +1,250 @@
+/**
+ * The TOML subset seisin.toml is written in: `[table.name]` headers, and
+ * `key = ["a", "b"]` / `key = "a"` values, with a line number on every error.
+ *
+ * Kept in-house so installing seisin pulls in no parser. If a config outgrows
+ * this subset, the config is doing too much.
+ */
+import { CONFIG_NAME } from "./layout.js";
+
+const RE_TABLE = /^\[([A-Za-z0-9_.\-]+)\]$/;
+const RE_PAIR = /^([A-Za-z0-9_\-]+)\s*=\s*(.+)$/;
+
+/**
+ * Names a table or key may not have.
+ *
+ * `[roles.__proto__]` does not show up in `Object.keys(roles)`, so `check`
+ * prints the roles that exist and says nothing — while every other role
+ * inherits whatever it declared. A config reading `[roles.frontend]` with no
+ * `writes` came out of the parser owning the entire repo and holding
+ * GITHUB_TOKEN, and no amount of reading the file would show it.
+ *
+ * The tables below are made with a null prototype, which stops the inheritance
+ * on its own. The names are refused as well, because a config containing them
+ * is not a config with a mistake in it.
+ */
+export const FORBIDDEN = new Set(["__proto__", "prototype", "constructor"]);
+
+/** A table with no prototype, so nothing is inherited into it. */
+export function dict() {
+  return Object.create(null);
+}
+
+export const isTable = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+
+/** Read a property only if the object actually has it. */
+export function own(obj, key) {
+  return obj && Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
+}
+
+/**
+ * Where each table and key of a parsed file was written, by dotted name.
+ *
+ * Kept beside the result rather than in it, so the object stays exactly the
+ * data that was written; loadConfig reads it to put a line number on a name it
+ * does not know.
+ */
+export const LINES = new WeakMap();
+
+/** Minimal TOML subset -> plain object. Throws with a line number on bad input. */
+export function parseToml(text) {
+  const out = dict();
+  const where = new Map();
+  LINES.set(out, where);
+  let table = out;
+  let tableName = "";
+  // "Last one wins" is TOML-ish and wrong for a permission file. A policy can
+  // look restrictive at the top and be cancelled forty lines down, and the
+  // person reviewing it reads the first block. Both shapes are refused.
+  const seenTables = new Set();
+  const seenKeys = new Set();
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    const line = stripComment(raw).trim();
+    if (!line) continue;
+
+    const header = RE_TABLE.exec(line);
+    if (header) {
+      tableName = header[1];
+      for (const part of tableName.split("."))
+        if (FORBIDDEN.has(part))
+          throw new Error(
+            `${CONFIG_NAME}:${i + 1}: "[${tableName}]" uses the reserved name "${part}". ` +
+            `A table named that would not appear as a role and would hand its settings to ` +
+            `every other one.`);
+      if (seenTables.has(tableName))
+        throw new Error(
+          `${CONFIG_NAME}:${i + 1}: [${tableName}] appears twice. ` +
+          `A later table would silently override the earlier one — put every setting for ` +
+          `${tableName} in one place.`);
+      seenTables.add(tableName);
+      tableName.split(".").forEach((_, k, parts) => {
+        const name = parts.slice(0, k + 1).join(".");
+        if (!where.has(name)) where.set(name, i + 1);
+      });
+      table = tableName.split(".").reduce((node, key, k, parts) => {
+        if (!Object.prototype.hasOwnProperty.call(node, key)) node[key] = dict();
+        else if (!isTable(node[key]))
+          throw new Error(
+            `${CONFIG_NAME}:${i + 1}: [${tableName}] — "${parts.slice(0, k + 1).join(".")}" is already ` +
+            `a value, not a table. One name cannot be both.`);
+        return node[key];
+      }, out);
+      continue;
+    }
+
+    const pair = RE_PAIR.exec(line);
+    if (!pair) throw new Error(`${CONFIG_NAME}:${i + 1}: cannot read "${raw.trim()}"`);
+
+    let [, key, value] = pair;
+    const at = i + 1;
+    // An array may span lines; keep pulling until the brackets balance. Only
+    // the new line is searched: searching the whole growing value made an
+    // unclosed array of 100k lines take 20 s to be refused. A `]` inside a
+    // quoted item does not close it — `["a]b",` used to end the array there.
+    if (value.startsWith("[") && !closesArray(value)) {
+      const parts = [value];
+      let closed = false;
+      while (!closed && i + 1 < lines.length) {
+        const next = stripComment(lines[++i]).trim();
+        parts.push(next);
+        closed = closesArray(next);
+      }
+      value = parts.join(" ");
+    }
+    if (FORBIDDEN.has(key))
+      throw new Error(`${CONFIG_NAME}:${i + 1}: "${key}" is a reserved name and cannot be a setting.`);
+    const seen = `${tableName}.${key}`;
+    if (seenKeys.has(seen))
+      throw new Error(
+        `${CONFIG_NAME}:${i + 1}: "${key}" is set twice in [${tableName || "the root"}]. ` +
+        `The second would win, which is not a thing a permission file should do quietly.`);
+    seenKeys.add(seen);
+    where.set(tableName ? `${tableName}.${key}` : key, at);
+    /**
+     * A key may not be a table that is declared elsewhere, in either order.
+     *
+     * `[roles.a]` with `network = []`, then `[roles]` and `a = true` forty lines
+     * down, used to replace the whole role with `true`: its `network = []` came
+     * back as "not set", which means the global allow list. `check` said
+     * nothing. It is the "last one wins" this parser refuses everywhere else,
+     * arriving by a different spelling.
+     */
+    if (Object.prototype.hasOwnProperty.call(table, key))
+      throw new Error(
+        `${CONFIG_NAME}:${i + 1}: "${key}" in [${tableName || "the root"}] is already the table ` +
+        `[${tableName ? tableName + "." : ""}${key}]. One name cannot be both — the value would replace ` +
+        `everything that table says.`);
+    table[key] = readValue(value, i + 1);
+  }
+  return out;
+}
+
+/** Is there a `]` on this line outside a quoted string? Strings do not span lines. */
+export function closesArray(line) {
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"') quoted = !quoted;
+    else if (c === "]" && !quoted) return true;
+  }
+  return false;
+}
+
+/** Strips a trailing `#` comment, but not one inside a quoted string. */
+export function stripComment(line) {
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i];
+    if (c === '"') quoted = !quoted;
+    else if (c === "#" && !quoted) return line.slice(0, i);
+  }
+  return line;
+}
+
+/**
+ * One value, read strictly.
+ *
+ * Strict is the whole point, and it was not before. The array reader used to
+ * pick quoted runs out of the line with a regex and ignore everything between
+ * them, so `["a" GARBAGE "b"]` parsed as `["a","b"]` and an unterminated string
+ * parsed as `""`. A permission file that is half-understood is worse than one
+ * that is rejected: the half that was dropped is the half you meant.
+ *
+ * So this scans rather than matches, and anything it does not recognise is an
+ * error with a line number. There are no escapes — a `"` ends the string. If a
+ * path of yours needs a quote in it, that is outside this subset and the
+ * message says so instead of guessing.
+ */
+function readValue(value, lineNo) {
+  const v = value.trim();
+  const bad = (msg) => { throw new Error(`${CONFIG_NAME}:${lineNo}: ${msg}`); };
+
+  if (v === "true") return true;
+  if (v === "false") return false;
+
+  if (v.startsWith('"')) {
+    const end = v.indexOf('"', 1);
+    if (end === -1) bad(`unterminated string — no closing quote in ${v}`);
+    const rest = v.slice(end + 1).trim();
+    if (rest) bad(`unexpected ${JSON.stringify(rest)} after the string`);
+    return v.slice(1, end);
+  }
+
+  if (v.startsWith("[")) {
+    if (!v.endsWith("]")) bad("unterminated array — no closing bracket");
+    const items = [];
+    let i = 1;
+    const body = v.slice(0, -1);          // everything up to the closing bracket
+    let expectItem = true;                // a list alternates item, comma, item…
+
+    while (i < body.length) {
+      const c = body[i];
+      if (c === " " || c === "\t") { i++; continue; }
+
+      if (c === ",") {
+        if (expectItem) bad("empty array slot — two commas in a row, or a leading comma");
+        expectItem = true; i++; continue;
+      }
+      if (!expectItem) bad(`missing comma before ${JSON.stringify(body.slice(i, i + 12))}`);
+      // Whole numbers, for `local_ports`. Digits only: no sign, no decimal, no
+      // underscore — a port is none of those, and every other key still
+      // refuses a number through asArray.
+      const digits = /^\d+/.exec(body.slice(i));
+      if (digits) {
+        const after = body[i + digits[0].length];
+        if (after !== undefined && after !== "," && after !== " " && after !== "\t")
+          bad(`${JSON.stringify(body.slice(i, i + 12))} is not a whole number`);
+        items.push(Number(digits[0]));
+        i += digits[0].length;
+        expectItem = false;
+        continue;
+      }
+      if (c !== '"') bad(`array items must be double-quoted, found ${JSON.stringify(body.slice(i, i + 12))}`);
+
+      const end = body.indexOf('"', i + 1);
+      if (end === -1) bad("unterminated string inside the array");
+      // A backslash before the closing quote means somebody wrote `\"` and
+      // expected an escape. There are none — the quote just ended the string,
+      // and the error they get otherwise is about a missing comma somewhere in
+      // the middle of a shell pipeline, which names the symptom and hides the
+      // cause. Measured while writing the docs: every attempt at a one-line
+      // provider command landed here.
+      if (body[end - 1] === "\\")
+        bad(`there are no escapes in this format, so the \\" in ` +
+            `${JSON.stringify(body.slice(i, Math.min(end + 2, i + 40)))} ended the string early.\n` +
+            `  A value cannot contain a double quote. If this is a shell command, put it in a ` +
+            `script and name the script instead — which is also how it stops being unreadable.`);
+      items.push(body.slice(i + 1, end));
+      i = end + 1;
+      expectItem = false;                 // a trailing comma is fine; a trailing item is not
+    }
+    return items;
+  }
+
+  if (/^\d+$/.test(v)) return Number(v);
+
+  bad("value must be a string, an array of strings, a whole number, or a boolean");
+}