claude-multiacc 2.0.30 → 2.0.32

package/bin/codex-accounts

@@ -70,6 +70,12 @@ USAGE
   codex-accounts remove <acct-NN> [--yes]   delete account (propagates to server)
   codex-accounts dedupe [--yes]             remove any account registered twice
                                             (same email), keeping one per email
+  codex-accounts configure [--max-subagents N] [--include-global] [--check] [--json]
+      explicitly manage Codex subagent concurrency for this pool (Python 3.11+).
+      Applies to existing and future manifest accounts; other settings stay intact.
+      --include-global also updates ~/.codex/config.toml; --check only reads settings.
+      Without --max-subagents, reads back the current policy. Changes stay local
+      until sync distributes the opted-in pool policy to its configured targets.
   codex-accounts sync [--no-server]         push manifest+seeds to the sync target AND
                                             any manifest 'peers' (extra machines). Mac
                                             only. auth.json is machine-local, NEVER
@@ -109,6 +115,23 @@ EOF
 
 require_manifest() { [ -f "$MANIFEST" ] || die "no manifest at $MANIFEST — run claude-multiacc install first"; }
 
+cmd_configure() {
+  require_manifest
+  local apply=0 check=0 arg rc
+  for arg in "$@"; do
+    case "$arg" in --max-subagents|--max-subagents=*) apply=1 ;; --check) check=1 ;; esac
+  done
+  if [ "$apply" = "1" ] && [ "$check" = "0" ]; then
+    mutate_lock || die "could not acquire the account settings lock; try again"
+    trap mutate_unlock EXIT
+  fi
+  "$PYBIN" "$LIB_DIR/codex_settings.py" configure "$ACC_ROOT" "$@"
+  rc=$?
+  mutate_unlock
+  trap - EXIT
+  return "$rc"
+}
+
 next_id() {
   local n=1 id
   while :; do
@@ -1960,6 +1983,14 @@ done" >>"$ACC_ROOT/sync.log" 2>&1 || fail "removal propagation on $server failed
   # Post-sync hook: the target seeds dirs and re-runs its quick verification matrix.
   # Non-fatal: a hook that is absent (not bootstrapped) or exits nonzero (accounts
   # awaiting a login THERE) must not fail the push that just succeeded.
+  if [ -f "$ACC_ROOT/codex-settings-policy.json" ]; then
+    local subagent_cap
+    subagent_cap="$("$PYBIN" "$LIB_DIR/codex_settings.py" policy-value "$ACC_ROOT")" \
+      || fail "cannot read opted-in Codex settings policy"
+    ssh -o BatchMode=yes "$server" \
+      "CODEX_ACCOUNTS_ROOT='$sroot' '$srepo/bin/codex-accounts' configure --max-subagents '$subagent_cap' --json" \
+      >>"$ACC_ROOT/sync.log" 2>&1 || fail "Codex settings policy was not verified on $server"
+  fi
   ssh -o BatchMode=yes "$server" "[ -x '$srepo/bin/codex-accounts' ] && '$srepo/bin/codex-accounts' post-sync" \
     >>"$ACC_ROOT/sync.log" 2>&1 || slog "post-sync hook on $server unavailable or unhappy (see its pool state)"
 }
@@ -2211,7 +2242,7 @@ PYEOF
 # distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
 # FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
 # the dispatcher below implements, and a test pins that both ways.
-_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync verify limits post-sync health self-update init-pool"
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool"
 case " $_KNOWN_VERBS " in
   *" ${1:-help} "*)
     for _arg in "$@"; do
@@ -2233,6 +2264,7 @@ case "${1:-help}" in
   expired) shift; cmd_expired "$@" ;;
   relogin|re-login) shift; cmd_relogin "$@" ;;
   sync) shift; cmd_sync "$@" ;;
+  configure) shift; cmd_configure "$@" ;;
   verify) shift; cmd_verify "$@" ;;
   limits) shift; cmd_limits "$@" ;;
   post-sync) shift; cmd_post_sync "$@" ;;

package/docs/CODEX.md

@@ -81,3 +81,50 @@ codex-accounts verify                 # real codex exec call per account
 codex-accounts --help                 # all account commands and options
 claude-multiacc codex status          # same status command via the npm wrapper
 ```
+
+## Opt-in subagent concurrency policy
+
+The addon does not choose delegation policy by default. To manage the concurrent
+subagent ceiling across one Codex pool, explicitly configure it (Python 3.11+):
+
+```bash
+codex-accounts configure --max-subagents 7 --include-global --json
+codex-accounts configure --max-subagents 7 --include-global --check --json
+```
+
+An explicitly selected modern Python is preserved. If the shell resolves an older
+system Python, this command tries already installed Python 3.11+ executables on
+PATH and in standard Homebrew locations, with bounded probes and no downloads.
+
+The first command sets `features.multi_agent_v2.max_concurrent_threads_per_session`
+and the compatible `agents.max_concurrent_threads_per_session` in every manifest
+account's `config.toml`, migrating its legacy `agents.max_threads` key when present.
+An existing boolean `multi_agent_v2` becomes a table with the same `enabled` value;
+an existing feature cap is updated along with the agents cap.
+`--include-global` also updates the machine's `~/.codex/config.toml`; without it,
+the global file is untouched. Unrelated models, instructions, MCP servers, project
+trust and custom agents remain intact. Retired directories outside the manifest
+are never changed. This is a concurrency ceiling per parent session, not an
+instruction to spawn that many agents or a pool-wide account limit.
+
+An opted-in pool persists `codex-settings-policy.json`. Future account seeding and
+local sync apply that policy to existing and new accounts. Normal remote sync
+explicitly configures and verifies the same pool policy on each target using its
+installed addon; update the target addon before syncing. A failed policy readback
+fails sync instead of reporting success. Remote sync does not change the target's
+global config. Without the policy file, existing settings keep their usual
+copy-only-if-missing behavior and no new remote command runs.
+
+`--check` never writes; it checks both caps against the persisted policy
+and requested value in selected configs, returning exit 1 on drift. Without
+`--max-subagents`, the command only reads the current pool policy and configuration. JSON reports contain
+the installed `plugin_version`, `max_subagents`, `policy_max_subagents`,
+`accounts_total`, `accounts_configured`, `global_configured`, `mismatch_count` and
+`verified`, without account identities, paths, credentials or arbitrary config.
+
+Conflicting profile overrides are rejected.
+Unusual inline-table layouts are also rejected before configuration changes;
+use ordinary `[agents]` and `[features.multi_agent_v2]` tables for the managed settings.
+All target configs are validated before writes, each replacement is atomic, and repeating the command
+repairs an interrupted write. Existing running sessions retain the settings they
+loaded; the policy applies to subsequent sessions.

package/lib/codex_config_edit.py

@@ -0,0 +1,92 @@
+"""Lossless, validated edits of Codex's per-session subagent limit (Python 3.11+)."""
+
+import copy
+import re
+try:
+    import tomllib
+except ImportError:
+    raise SystemExit("Codex settings configuration requires Python 3.11 or newer") from None
+
+KEY = "max_concurrent_threads_per_session"
+
+
+def limits(document):
+    """Report only delegation settings; never expose arbitrary configuration values."""
+    agents = document.get("agents", {})
+    feature = document.get("features", {}).get("multi_agent_v2")
+    override = feature.get(KEY) if isinstance(feature, dict) else None
+    configured = agents.get(KEY, agents.get("max_threads"))
+    return {"configured": configured, "feature_override": override,
+            "effective": override if override is not None else configured}
+
+
+def validate_overrides(document, value):
+    """Reject conflicting feature/profile overrides instead of silently missing the cap."""
+    for name, item in [("default", document), *document.get("profiles", {}).items()]:
+        if not isinstance(item, dict):
+            continue
+        current = limits(item)
+        if current["feature_override"] not in (None, value):
+            raise ValueError(f"{name}: features.multi_agent_v2 overrides the requested subagent limit")
+        if name != "default" and current["configured"] not in (None, value):
+            raise ValueError(f"{name}: profile overrides the requested subagent limit")
+
+
+def dotted_pattern(parts):
+    return r'\s*\.\s*'.join(r'(?:' + re.escape(part) + r'|"' + re.escape(part)
+                            + r'"|\x27' + re.escape(part) + r'\x27)' for part in parts)
+
+
+def edit_setting(source, table, key, literal, aliases=()):
+    """Edit table/dotted assignments, or remove one when literal is None."""
+    headers = [re.compile(r'^\s*\[\s*' + dotted_pattern(table[:depth]) + r'\s*\]\s*(?:#.*)?$')
+               for depth in range(1, len(table) + 1)]
+    assignments = [re.compile(r'^\s*(?:' + '|'.join(dotted_pattern((*table[depth:], name))
+                                                 for name in (key, *aliases)) + r')\s*=')
+                   for depth in range(len(table) + 1)]
+    section, output, inserted = 0, [], False
+    for line in source.splitlines(keepends=True):
+        if line.lstrip().startswith("["):
+            section = next((depth for depth, header in enumerate(headers, 1)
+                            if header.match(line.rstrip("\r\n"))), None)
+            if section == len(table) and literal is not None and not inserted:
+                output.extend([line.rstrip("\r\n") + "\n", f"{key} = {literal}\n"])
+                inserted = True
+                continue
+        if section is not None and assignments[section].match(line):
+            if literal is not None and not inserted:
+                output.append(f"{'.'.join((*table[section:], key))} = {literal}\n")
+                inserted = True
+            continue
+        output.append(line)
+    if literal is not None and not inserted:
+        output.extend([f"\n[{'.'.join(table)}]\n", f"{key} = {literal}\n"])
+    return "".join(output)
+
+
+def updated_config(source, value):
+    """Set the v2 feature cap and agents fallback, preserving enablement and unrelated values."""
+    original = tomllib.loads(source)
+    validate_overrides({"profiles": original.get("profiles", {})}, value)
+    expected = copy.deepcopy(original)
+    agents = expected.setdefault("agents", {})
+    agents.pop("max_threads", None)
+    agents[KEY] = value
+    features = expected.setdefault("features", {})
+    feature = features.get("multi_agent_v2")
+    result = edit_setting(source, ("agents",), KEY, value, ("max_threads",))
+    if isinstance(feature, bool):
+        result = edit_setting(result, ("features",), "multi_agent_v2", None)
+        result = edit_setting(result, ("features", "multi_agent_v2"), "enabled", str(feature).lower())
+        features["multi_agent_v2"] = {"enabled": feature}
+    elif feature is None:
+        features["multi_agent_v2"] = {}
+    features["multi_agent_v2"][KEY] = value
+    result = edit_setting(result, ("features", "multi_agent_v2"), KEY, value)
+    try:
+        unchanged = tomllib.loads(result) == expected
+    except tomllib.TOMLDecodeError:
+        unchanged = False
+    if not unchanged:
+        raise ValueError("unsupported Codex TOML layout; use normal [agents] and [features.multi_agent_v2] tables")
+    return result

package/lib/codex_python.py

@@ -0,0 +1,27 @@
+"""Find an already installed TOML-capable Python when stock macOS Python is older."""
+
+import os
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+
+
+def require_python311(script):
+    if sys.version_info >= (3, 11):
+        return
+    names = ["python3.14", "python3.13", "python3.12", "python3.11"]
+    candidates = [shutil.which(name) for name in names]
+    candidates.extend(str(Path(prefix) / name)
+                      for prefix in ("/opt/homebrew/bin", "/usr/local/bin") for name in names)
+    for candidate in dict.fromkeys(candidates):
+        if not candidate or not os.access(candidate, os.X_OK):
+            continue
+        try:
+            probe = subprocess.run([candidate, "-c", "import sys;sys.exit(sys.version_info < (3,11))"],
+                                   capture_output=True, check=False, timeout=3)
+            if probe.returncode == 0:
+                os.execv(candidate, [candidate, str(script), *sys.argv[1:]])
+        except (OSError, subprocess.TimeoutExpired):
+            continue
+    raise SystemExit("Codex settings configuration requires an installed Python 3.11 or newer")

package/lib/codex_settings.py

@@ -0,0 +1,171 @@
+"""Explicit pool-owned Codex settings, applied only after an operator opts in."""
+
+import argparse
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import tempfile
+
+from codex_python import require_python311
+
+require_python311(__file__)
+
+from codex_config_edit import limits, tomllib, updated_config, validate_overrides
+
+POLICY_FILE = "codex-settings-policy.json"
+
+
+def positive_integer(value):
+    if isinstance(value, bool) or not re.fullmatch(r"[0-9]+", str(value)):
+        raise ValueError("max-subagents must be a positive integer")
+    parsed = int(value)
+    if parsed < 1:
+        raise ValueError("max-subagents must be a positive integer")
+    return parsed
+
+
+def policy_value(root):
+    path = root / POLICY_FILE
+    if not path.exists():
+        return None
+    policy = json.loads(path.read_text())
+    if policy.get("version") != 1:
+        raise ValueError("unsupported Codex settings policy version")
+    return positive_integer(policy["max_subagents"])
+
+
+def target_paths(root, include_global):
+    manifest = json.loads((root / "accounts.json").read_text())
+    accounts = manifest.get("accounts")
+    if not isinstance(accounts, list):
+        raise ValueError("manifest accounts must be a list")
+    result = []
+    for account in accounts:
+        account_id = account.get("id", "") if isinstance(account, dict) else ""
+        if not re.fullmatch(r"acct-\d{2}", account_id):
+            raise ValueError("manifest has an invalid account id")
+        result.append(root / account_id / "config.toml")
+    if include_global:
+        result.append(Path.home() / ".codex" / "config.toml")
+    return list(dict.fromkeys(result))
+
+
+def atomic_write(path, text):
+    target = path.resolve()
+    target.parent.mkdir(parents=True, exist_ok=True)
+    mode = target.stat().st_mode & 0o777 if target.exists() else 0o600
+    descriptor, name = tempfile.mkstemp(prefix=".codex-settings-", dir=target.parent)
+    try:
+        with os.fdopen(descriptor, "w") as handle:
+            os.fchmod(handle.fileno(), mode)
+            handle.write(text)
+        os.replace(name, target)
+    finally:
+        if os.path.exists(name):
+            os.unlink(name)
+
+
+def configure(root, paths, value):
+    pending, seen = [], set()
+    for path in paths:
+        if path.resolve() in seen:
+            continue
+        seen.add(path.resolve())
+        previous = path.read_text() if path.exists() else ""
+        source = previous
+        if not path.exists() and path != Path.home() / ".codex/config.toml":
+            global_config = Path.home() / ".codex/config.toml"
+            source = global_config.read_text() if global_config.exists() else ""
+        pending.append((path, previous, updated_config(source, value)))
+    for path, previous, updated in pending:
+        if (path.read_text() if path.exists() else "") != previous:
+            raise ValueError("configuration changed during validation; retry configure")
+        if updated != previous:
+            atomic_write(path, updated)
+    atomic_write(root / POLICY_FILE, json.dumps({"version": 1, "max_subagents": value}) + "\n")
+
+
+def readback(paths, value):
+    result = {}
+    for path in paths:
+        document = tomllib.loads(path.read_text()) if path.exists() else {}
+        current = limits(document)
+        matches = (all(current[key] == value for key in ("configured", "feature_override"))
+                   if value is not None else True)
+        try:
+            validate_overrides(document, value)
+        except ValueError:
+            matches = False
+        result[path] = matches
+    return result
+
+
+def plugin_version():
+    repo = Path(__file__).resolve().parents[1]
+    if (repo / ".git").exists():
+        try:
+            result = subprocess.run(["git", "describe", "--tags", "--exact-match"], cwd=repo,
+                                    capture_output=True, text=True, check=False, timeout=5)
+            tag = result.stdout.strip()
+            if result.returncode == 0 and re.fullmatch(r"v\d+\.\d+\.\d+", tag):
+                return tag[1:]
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+    return str(json.loads((repo / "package.json").read_text())["version"])
+
+
+def report_for(root, paths, value, include_global):
+    matches = readback(paths, value)
+    global_path = Path.home() / ".codex/config.toml"
+    global_configured = matches.pop(global_path, None) if include_global else None
+    configured, total = sum(matches.values()), len(matches)
+    policy = policy_value(root)
+    mismatches = total - configured + int(global_configured is False)
+    return {"provider": "codex", "plugin_version": plugin_version(), "max_subagents": value,
+            "policy_max_subagents": policy, "accounts_total": total, "accounts_configured": configured,
+            "global_configured": global_configured, "mismatch_count": mismatches,
+            "verified": mismatches == 0 and policy == value}
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("mode", choices=("configure", "seed", "policy-value"))
+    parser.add_argument("root", type=Path)
+    parser.add_argument("--max-subagents", type=positive_integer)
+    parser.add_argument("--include-global", action="store_true")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--account-dir", type=Path)
+    args = parser.parse_args()
+    value = args.max_subagents if args.max_subagents is not None else policy_value(args.root)
+    if args.mode == "policy-value":
+        if value is not None:
+            print(value)
+        return
+    if args.mode == "seed":
+        if value is not None:
+            path = args.account_dir / "config.toml"
+            source = path.read_text() if path.exists() else ""
+            updated = updated_config(source, value)
+            if source != updated:
+                atomic_write(path, updated)
+        return
+    paths = target_paths(args.root, args.include_global)
+    if args.max_subagents is not None and not args.check:
+        configure(args.root, paths, value)
+    report = report_for(args.root, paths, value, args.include_global)
+    print(json.dumps(report) if args.json else
+          f"Codex subagent policy: {value if value is not None else 'unmanaged'}; checked {len(paths)} configs")
+    if not report["verified"]:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        print(f"codex-accounts configure: {error}", file=sys.stderr)
+        sys.exit(1)

package/lib/common.sh

@@ -691,6 +691,10 @@ seed_account_dir() { # $1 = acct dir
     if [ ! -f "$d/config.toml" ] && [ -f "$HOME/.codex/config.toml" ]; then
       cp "$HOME/.codex/config.toml" "$d/config.toml" 2>/dev/null || true
     fi
+    if [ -f "$ACC_ROOT/codex-settings-policy.json" ]; then
+      "$PYBIN" "$LIB_DIR/codex_settings.py" seed "$ACC_ROOT" --account-dir "$d" \
+        || die "could not apply the opted-in Codex settings policy"
+    fi
     if [ ! -e "$d/sessions" ] && [ -d "$HOME/.codex/sessions" ]; then
       ln -s "$HOME/.codex/sessions" "$d/sessions" 2>/dev/null || true
     fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.30",
+  "version": "2.0.32",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {
@@ -57,7 +57,8 @@
     "postinstall": "node scripts/postinstall.mjs",
     "test": "npm run test:core && npm run test:seeding && npm run test:commands",
     "test:core": "bash tests/run-tests.sh && python3 tests/test_selector.py",
-    "test:seeding": "python3 tests/test_account_seeding.py",
+    "test:seeding": "python3 tests/test_account_seeding.py && npm run test:codex-settings",
+    "test:codex-settings": "python3 tests/test_codex_config_edit.py && python3 tests/test_codex_settings.py",
     "test:commands": "python3 tests/test_packaged_commands.py"
   },
   "dependencies": {

package/tests/test_codex_config_edit.py

@@ -0,0 +1,98 @@
+"""Prove a subagent policy edit preserves unrelated parsed settings and source text."""
+
+from pathlib import Path
+import sys
+import tomllib
+import unittest
+from unittest import mock
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "lib"))
+from codex_config_edit import KEY, updated_config
+from codex_python import require_python311
+
+
+class CodexConfigEditTests(unittest.TestCase):
+    def test_models_comments_and_custom_agents_survive(self):
+        source = ('# personal preference\nmodel = "chosen"\n[agents]\nmax_threads = 4\n'
+                  'max_depth = 2\n[agents.reviewer]\ndescription = "review"\n'
+                  '[features]\nmulti_agent_v2 = true\n[mcp_servers.example]\ncommand = "example"\n')
+        updated = updated_config(source, 8)
+        self.assertEqual(tomllib.loads(updated)["agents"][KEY], 8)
+        self.assertNotIn("max_threads", tomllib.loads(updated)["agents"])
+        for preserved in ('# personal preference', 'model = "chosen"', 'max_depth = 2',
+                          'description = "review"', 'command = "example"'):
+            self.assertIn(preserved, updated)
+        self.assertEqual(updated_config(updated, 8), updated)
+
+    def test_empty_regular_and_dotted_layouts_are_idempotent(self):
+        for source in ("", '[features]\nmulti_agent_v2 = true',
+                       'agents.max_threads = 4\nmodel = "chosen"\n',
+                       '["agents"] # preference\nmax_concurrent_threads_per_session = 2\n'):
+            with self.subTest(source=source):
+                updated = updated_config(source, 8)
+                self.assertEqual(tomllib.loads(updated)["agents"][KEY], 8)
+                self.assertEqual(updated_config(updated, 8), updated)
+
+    def test_conflicting_profile_overrides_are_rejected(self):
+        for source in ('[profiles.quick.features.multi_agent_v2]\nmax_concurrent_threads_per_session = 20\n',
+                       '[profiles.quick.agents]\nmax_threads = 20\n'):
+            with self.subTest(source=source), self.assertRaisesRegex(ValueError, "overrides"):
+                updated_config(source, 8)
+        source = '[features.multi_agent_v2]\nmax_concurrent_threads_per_session = 8\n'
+        self.assertEqual(tomllib.loads(updated_config(source, 8))["agents"][KEY], 8)
+
+    def test_existing_eight_thread_policies_and_feature_overrides_change_to_seven(self):
+        for feature in ('[features]\nmulti_agent_v2 = true\n',
+                        '[features]\nmulti_agent_v2 = false\n',
+                        '[features.multi_agent_v2]\nenabled = true\nmax_concurrent_threads_per_session = 20\n',
+                        'features.multi_agent_v2.max_concurrent_threads_per_session = 8\n',
+                        '[features]\nmulti_agent_v2.max_concurrent_threads_per_session = 8\n'):
+            source = feature + '[agents]\nmax_concurrent_threads_per_session = 8\n'
+            with self.subTest(feature=feature):
+                updated = updated_config(source, 7)
+                document = tomllib.loads(updated)
+                self.assertEqual(document["agents"][KEY], 7)
+                self.assertEqual(document["features"]["multi_agent_v2"][KEY], 7)
+                if 'false' in feature:
+                    self.assertFalse(document["features"]["multi_agent_v2"]["enabled"])
+                self.assertEqual(updated_config(updated, 7), updated)
+
+    def test_unsupported_layouts_and_string_lookalikes_fail_safely(self):
+        for source in ('agents = { max_threads = 4 }\n',
+                       'instructions = """\n[agents]\nmax_threads = 99\n"""\n'):
+            with self.subTest(source=source), self.assertRaisesRegex(ValueError, "unsupported"):
+                updated_config(source, 8)
+
+
+class CodexPythonTests(unittest.TestCase):
+    def test_explicit_modern_python_is_preserved(self):
+        with mock.patch("codex_python.sys.version_info", (3, 12)), \
+                mock.patch("codex_python.subprocess.run") as probe:
+            require_python311("settings.py")
+        probe.assert_not_called()
+
+    def test_old_python_reexecutes_available_modern_interpreter_with_same_args(self):
+        with mock.patch("codex_python.sys.version_info", (3, 9)), \
+                mock.patch("codex_python.shutil.which", return_value="/installed/python3.12"), \
+                mock.patch("codex_python.os.access", return_value=True), \
+                mock.patch("codex_python.sys.argv", ["settings.py", "configure", "pool", "--check"]), \
+                mock.patch("codex_python.subprocess.run", return_value=mock.Mock(returncode=0)) as probe, \
+                mock.patch("codex_python.os.execv", side_effect=SystemExit(42)) as replace:
+            with self.assertRaises(SystemExit):
+                require_python311("settings.py")
+        self.assertEqual(probe.call_args.kwargs["timeout"], 3)
+        replace.assert_called_once_with("/installed/python3.12",
+                                        ["/installed/python3.12", "settings.py", "configure", "pool", "--check"])
+
+    def test_missing_modern_python_fails_without_downloads(self):
+        with mock.patch("codex_python.sys.version_info", (3, 9)), \
+                mock.patch("codex_python.shutil.which", return_value=None), \
+                mock.patch("codex_python.os.access", return_value=False), \
+                mock.patch("codex_python.subprocess.run") as probe:
+            with self.assertRaisesRegex(SystemExit, "requires an installed Python 3.11"):
+                require_python311("settings.py")
+        probe.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tests/test_codex_settings.py

@@ -0,0 +1,148 @@
+"""Exercise the public opt-in CLI with isolated pools and no provider/credential access."""
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import tomllib
+import unittest
+
+REPO = Path(__file__).resolve().parents[1]
+KEY = "max_concurrent_threads_per_session"
+
+
+class CodexSettingsTests(unittest.TestCase):
+    def setUp(self):
+        self.work = tempfile.TemporaryDirectory()
+        self.addCleanup(self.work.cleanup)
+        self.home = Path(self.work.name)
+        self.pool = self.home / "pool"
+        self.pool.mkdir()
+        (self.home / ".codex").mkdir()
+        self.global_config = self.home / ".codex/config.toml"
+        self.global_config.write_text('model = "global"\n[features]\nmulti_agent_v2 = true\n')
+        self.manifest = {"version": 1, "server": "none", "accounts": [
+            {"id": "acct-01", "email": "fixture@example.test", "home": "mac"}]}
+        (self.pool / "accounts.json").write_text(json.dumps(self.manifest))
+        self.account = self.pool / "acct-01/config.toml"
+        self.account.parent.mkdir()
+        self.account.write_text('model = "account"\n[agents]\nmax_threads = 3\n')
+        self.env = {**os.environ, "HOME": str(self.home), "CODEX_ACCOUNTS_ROOT": str(self.pool),
+                    "CLAUDE_MULTIACC_PYTHON": "python3"}
+
+    def command(self, *args):
+        return subprocess.run([str(REPO / "bin/codex-accounts"), *args],
+                              env=self.env, capture_output=True, text=True, check=False)
+
+    def test_configure_opt_in_preserves_other_settings_and_retired_dirs(self):
+        retired = self.pool / "acct-99/config.toml"
+        retired.parent.mkdir()
+        retired.write_text("retired = true\n")
+        original_global = self.global_config.read_text()
+        for _ in range(2):
+            result = self.command("configure", "--max-subagents", "8", "--json")
+            self.assertEqual(result.returncode, 0, result.stderr)
+            report = json.loads(result.stdout)
+            self.assertTrue(report["verified"])
+            self.assertEqual(report["accounts_total"], 1)
+            self.assertEqual(report["accounts_configured"], 1)
+            self.assertNotIn("acct-01", result.stdout)
+            self.assertNotIn("fixture@example", result.stdout)
+        self.assertEqual(tomllib.loads(self.account.read_text())["model"], "account")
+        self.assertEqual(self.global_config.read_text(), original_global)
+        self.assertEqual(retired.read_text(), "retired = true\n")
+
+    def test_global_opt_in_and_read_only_drift_detection(self):
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(json.loads(result.stdout)["global_configured"])
+        self.account.write_text('[agents]\nmax_concurrent_threads_per_session = 20\n')
+        before = self.account.read_text()
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--check", "--json")
+        self.assertEqual(result.returncode, 1)
+        self.assertEqual(json.loads(result.stdout)["mismatch_count"], 1)
+        self.assertFalse(json.loads(result.stdout)["verified"])
+        self.assertEqual(self.account.read_text(), before)
+
+    def test_future_seeding_and_local_sync_apply_policy(self):
+        result = self.command("configure", "--max-subagents", "8")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.manifest["accounts"].append({"id": "acct-02", "email": "new@example.test", "home": "mac"})
+        (self.pool / "accounts.json").write_text(json.dumps(self.manifest))
+        self.account.write_text('model = "changed"\n')
+        result = self.command("sync", "--no-server")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        for path in (self.account, self.pool / "acct-02/config.toml"):
+            self.assertEqual(tomllib.loads(path.read_text())["agents"][KEY], 8)
+        self.assertEqual(tomllib.loads(self.account.read_text())["model"], "changed")
+
+    def test_invalid_config_is_rejected_before_any_configuration_is_changed(self):
+        before = self.account.read_text()
+        self.global_config.write_text('[profiles.quick.features.multi_agent_v2]\n'
+                                      'max_concurrent_threads_per_session = 20\n')
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--json")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("overrides", result.stderr)
+        self.assertEqual(self.account.read_text(), before)
+        self.assertFalse((self.pool / "codex-settings-policy.json").exists())
+
+    def test_seven_thread_policy_requires_v2_setting_and_repairs_legacy_only_configs(self):
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        result = self.command("configure", "--max-subagents", "7", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        for path in (self.account, self.global_config):
+            config = tomllib.loads(path.read_text())
+            self.assertEqual(config["features"]["multi_agent_v2"][KEY], 7)
+            self.assertEqual(config["agents"][KEY], 7)
+        self.account.write_text('[agents]\nmax_concurrent_threads_per_session = 7\n')
+        result = self.command("configure", "--include-global", "--check", "--json")
+        self.assertEqual(result.returncode, 1, result.stderr)
+        self.assertEqual(json.loads(result.stdout)["mismatch_count"], 1)
+        result = self.command("configure", "--max-subagents", "7", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(json.loads(result.stdout)["verified"])
+
+    def test_symlinked_global_config_remains_linked(self):
+        self.account.unlink()
+        self.account.symlink_to(self.global_config)
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(self.account.is_symlink())
+        self.assertTrue(json.loads(result.stdout)["verified"])
+
+    @unittest.skipUnless(Path("/usr/bin/python3").is_file(), "System Python required")
+    def test_configuration_via_system_python_uses_installed_modern_runtime(self):
+        self.env["CLAUDE_MULTIACC_PYTHON"] = "/usr/bin/python3"
+        result = self.command("configure", "--max-subagents", "8", "--include-global", "--json")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        self.assertTrue(json.loads(result.stdout)["verified"])
+
+    def test_sync_verifies_opted_in_policy_on_remote_target(self):
+        result = self.command("configure", "--max-subagents", "8")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        tools = self.home / "tools"
+        tools.mkdir()
+        for name, body in {"uname": "echo Darwin", "rsync": "exit 0",
+                           "ssh": 'printf "%s\\n" "$*" >> "$HOME/ssh-calls"\nexit 0'}.items():
+            path = tools / name
+            path.write_text("#!/bin/sh\n" + body + "\n")
+            path.chmod(0o755)
+        self.env.update({"PATH": str(tools) + os.pathsep + self.env["PATH"],
+                         "CODEX_MULTIACC_SYNC_TARGET": "operator@runner",
+                         "CODEX_MULTIACC_SYNC_ROOT": "/remote/pool",
+                         "CODEX_MULTIACC_SYNC_REPO": "/remote/plugin"})
+        result = self.command("sync")
+        self.assertEqual(result.returncode, 0, result.stderr)
+        calls = (self.home / "ssh-calls").read_text()
+        self.assertIn("configure --max-subagents '8' --json", calls)
+        self.assertIn("CODEX_ACCOUNTS_ROOT='/remote/pool'", calls)
+        (tools / "ssh").write_text('#!/bin/sh\ncase "$*" in *configure*) exit 1 ;; esac\nexit 0\n')
+        result = self.command("sync")
+        self.assertNotEqual(result.returncode, 0)
+        self.assertIn("settings policy was not verified", result.stderr)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tests/test_packaged_commands.py

@@ -75,6 +75,18 @@ class PackagedCommandsTests(unittest.TestCase):
                     result = run(prefix + ["verify"] + flags, self.env, self.work)
                     self.assertEqual(result.returncode, 0, result.stderr)
                     self.assertIn(f"{provider}@example.test{expected}", result.stdout)
+        for prefix in (["codex-accounts"], ["claude-multiacc", "codex"]):
+            for check in ([], ["--check"]):
+                result = run(prefix + ["configure", "--max-subagents", "8", "--include-global", "--json"]
+                             + check, self.env, self.work)
+                self.assertEqual(result.returncode, 0, result.stderr)
+                report = json.loads(result.stdout)
+                self.assertTrue(report["verified"])
+                self.assertTrue(report["global_configured"])
+                self.assertEqual(report["accounts_configured"], 1)
+                self.assertEqual(report["plugin_version"],
+                                 json.loads((self.package / "package.json").read_text())["version"])
+                self.assertNotIn("acct-01", result.stdout)
 
     def test_self_update_uses_the_running_install_prefix(self):
         fake_npm = self.prefix / "bin/npm"