claude-multiacc 2.0.29 → 2.0.31

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/ACCOUNT_OPERATIONS.md

@@ -131,6 +131,15 @@ manually via:
 claude-accounts sync      # and codex-accounts sync for the codex pool
 ```
 
+Account creation and sync seed missing settings from the machine's default provider
+directory and link its global instructions: `~/.claude/CLAUDE.md` for Claude,
+`~/.codex/AGENTS.md` for Codex. Existing account settings (including models) and
+instruction files or links are preserved. The addon does not generate instructions
+or enable/disable agents. To share newly created global instructions with existing
+accounts, run `claude-accounts sync --no-server` and/or `codex-accounts sync --no-server`.
+This only repairs accounts in the manifest, leaving retired directories untouched.
+Global instruction files remain machine-local; sync does not copy them between hosts.
+
 Targets are the resolved sync target — env override, else the manifest's
 `server`/`server_root`/`server_repo` (the Linux box), see *Pointing sync somewhere else*
 below — plus an optional `peers` array for additional machines (e.g. a second Mac):

package/docs/CODEX.md

@@ -81,3 +81,47 @@ 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 8 --include-global --json
+codex-accounts configure --max-subagents 8 --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 `agents.max_concurrent_threads_per_session` in every manifest
+account's `config.toml`, migrating its legacy `agents.max_threads` key when present.
+`--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 the requested value against the persisted policy
+and 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 or `features.multi_agent_v2` object overrides are rejected.
+Unusual inline-table layouts are also rejected before configuration changes;
+use an ordinary `[agents]` table for the managed setting. 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,71 @@
+"""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"
+ALIASES = (KEY, "max_threads")
+
+
+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 updated_config(source, value):
+    """Edit ordinary [agents] or dotted keys, then prove no unrelated TOML value changed."""
+    original = tomllib.loads(source)
+    validate_overrides(original, value)
+    expected = copy.deepcopy(original)
+    agents = expected.setdefault("agents", {})
+    agents.pop("max_threads", None)
+    agents[KEY] = value
+    lines, section, output, inserted = source.splitlines(keepends=True), "", [], False
+    header = re.compile(r'^\s*\[\s*(?:agents|"agents"|\x27agents\x27)\s*\]\s*(?:#.*)?$')
+    assignment = re.compile(r'^\s*(?:"|\x27)?(?:' + '|'.join(ALIASES) + r')(?:"|\x27)?\s*=')
+    dotted = re.compile(r'^\s*agents\s*\.\s*(?:' + '|'.join(ALIASES) + r')\s*=')
+    for line in lines:
+        if header.match(line.rstrip("\r\n")):
+            section = "agents"
+            output.extend([line.rstrip("\r\n") + "\n", f"{KEY} = {value}\n"])
+            inserted = True
+            continue
+        if line.lstrip().startswith("["):
+            section = "other"
+        if (section == "agents" and assignment.match(line)) or (not section and dotted.match(line)):
+            continue
+        output.append(line)
+    if not inserted:
+        if any(dotted.match(line) for line in lines):
+            output.insert(0, f"agents.{KEY} = {value}\n")
+        else:
+            output.extend(["\n[agents]\n", f"{KEY} = {value}\n"])
+    result = "".join(output)
+    try:
+        unchanged = tomllib.loads(result) == expected
+    except tomllib.TOMLDecodeError:
+        unchanged = False
+    if not unchanged:
+        raise ValueError("unsupported agents TOML layout; use a normal [agents] table before configuring")
+    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,169 @@
+"""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 {}
+        matches = limits(document)["effective"] == value 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

@@ -677,7 +677,7 @@ codex_share_state_index() { # $1 acct dir — seed time: whatever index names ex
 }
 
 # Seed an account config dir so headless runs never prompt.
-#   claude: stripped .claude.json, copied settings.json, shared projects/ symlink
+#   claude: stripped .claude.json, copied settings.json, shared CLAUDE.md + projects/
 #           (shared history => --continue/--resume work regardless of picked account).
 #   codex:  copied config.toml (carries project trust + settings, no identity),
 #           shared sessions/ symlink (=> `codex resume` finds every session) with the
@@ -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
@@ -718,6 +722,9 @@ PYEOF
   if [ ! -f "$d/settings.json" ] && [ -f "$HOME/.claude/settings.json" ]; then
     cp "$HOME/.claude/settings.json" "$d/settings.json" 2>/dev/null || true
   fi
+  if [ ! -e "$d/CLAUDE.md" ] && [ -f "$HOME/.claude/CLAUDE.md" ]; then
+    ln -s "$HOME/.claude/CLAUDE.md" "$d/CLAUDE.md" 2>/dev/null || true
+  fi
   if [ ! -e "$d/projects" ] && [ -d "$HOME/.claude/projects" ]; then
     ln -s "$HOME/.claude/projects" "$d/projects" 2>/dev/null || true
   fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multiacc",
-  "version": "2.0.29",
+  "version": "2.0.31",
   "description": "Unified Claude Code and OpenAI Codex subscription pooling with quota-aware selection.",
   "type": "module",
   "bin": {
@@ -55,7 +55,10 @@
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.mjs",
-    "test": "bash tests/run-tests.sh && python3 tests/test_selector.py && npm run test:commands",
+    "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 && 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_account_seeding.py

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""Account seeding preserves settings and shares machine-local global instructions."""
+
+import json
+import os
+from pathlib import Path
+import subprocess
+import tempfile
+import unittest
+
+
+REPO = Path(__file__).resolve().parents[1]
+PROVIDERS = (("claude", "CLAUDE.md", "settings.json"), ("codex", "AGENTS.md", "config.toml"))
+
+
+class AccountSeedingTests(unittest.TestCase):
+    def setUp(self):
+        self.work = tempfile.TemporaryDirectory()
+        self.addCleanup(self.work.cleanup)
+        self.home = Path(self.work.name)
+        self.env = {**os.environ, "HOME": str(self.home), "CLAUDE_MULTIACC_PYTHON": "python3"}
+        for provider, _, _ in PROVIDERS:
+            (self.home / f".{provider}").mkdir()
+            self.env[f"{provider.upper()}_ACCOUNTS_ROOT"] = str(self.home / f".{provider}-accounts")
+
+    def seed(self, provider, directory=None):
+        account = directory or self.home / f".{provider}-accounts" / "acct-01"
+        subprocess.run(
+            ["bash", "-c", '. "$1"; seed_account_dir "$2"', "seed", str(REPO / "lib/common.sh"), str(account)],
+            env={**self.env, "MULTIACC_PROVIDER": provider}, check=True, capture_output=True, text=True,
+        )
+        return account
+
+    def test_instructions_are_shared_and_updates_remain_visible(self):
+        for provider, name, _ in PROVIDERS:
+            with self.subTest(provider=provider):
+                source = self.home / f".{provider}" / name
+                source.write_text("Global preferences\n")
+                account = self.seed(provider)
+                self.assertTrue((account / name).is_symlink())
+                self.assertEqual((account / name).resolve(), source.resolve())
+                source.write_text("Updated preferences\n")
+                self.seed(provider)
+                self.assertEqual((account / name).read_text(), "Updated preferences\n")
+
+    def test_existing_files_and_links_are_preserved(self):
+        for provider, name, _ in PROVIDERS:
+            with self.subTest(provider=provider):
+                (self.home / f".{provider}" / name).write_text("Global preferences\n")
+                account = self.seed(provider)
+                target = account / name
+                target.unlink()
+                target.write_text("Account preferences\n")
+                self.seed(provider)
+                self.assertFalse(target.is_symlink())
+                self.assertEqual(target.read_text(), "Account preferences\n")
+                target.unlink()
+                local = self.home / f"{provider}-local.md"
+                target.symlink_to(local)
+                self.seed(provider)
+                self.assertEqual(target.readlink(), local)  # Dangling custom link is also owned by the user.
+                local.write_text("Custom preferences\n")
+                self.seed(provider)
+                self.assertEqual(target.read_text(), "Custom preferences\n")
+
+    def test_missing_global_file_never_creates_a_dangling_or_self_link(self):
+        for provider, name, _ in PROVIDERS:
+            with self.subTest(provider=provider):
+                account = self.seed(provider)
+                self.assertFalse(os.path.lexists(account / name))
+                base = self.home / f".{provider}"
+                self.seed(provider, base)
+                self.assertFalse(os.path.lexists(base / name))
+                (base / name).write_text("Global preferences\n")
+                self.seed(provider, base)
+                self.assertFalse((base / name).is_symlink())
+
+    def test_existing_settings_and_model_are_not_overwritten(self):
+        for provider, _, name in PROVIDERS:
+            with self.subTest(provider=provider):
+                source = self.home / f".{provider}" / name
+                source.write_text('{"model":"global"}\n' if provider == "claude" else 'model = "global"\n')
+                account = self.seed(provider)
+                self.assertEqual((account / name).read_bytes(), source.read_bytes())
+                original = '{"model":"account"}\n' if provider == "claude" else 'model = "account"\n'
+                (account / name).write_text(original)
+                self.seed(provider)
+                self.assertEqual((account / name).read_text(), original)
+
+    def test_local_sync_repairs_only_manifest_accounts(self):
+        for provider, name, _ in PROVIDERS:
+            with self.subTest(provider=provider):
+                (self.home / f".{provider}" / name).write_text("Global preferences\n")
+                root = self.home / f".{provider}-accounts"
+                (root / "acct-01").mkdir(parents=True)
+                (root / "acct-99").mkdir()
+                (root / "accounts.json").write_text(json.dumps({
+                    "version": 1, "server": "none",
+                    "accounts": [{"id": "acct-01", "email": "fixture@example.test", "home": "mac"}],
+                }))
+                for _ in range(2):
+                    result = subprocess.run(
+                        [str(REPO / "bin" / f"{provider}-accounts"), "sync", "--no-server"],
+                        env=self.env, check=True, capture_output=True, text=True,
+                    )
+                    self.assertIn("nothing pushed", result.stdout)
+                self.assertTrue((root / "acct-01" / name).is_symlink())
+                self.assertFalse(os.path.lexists(root / "acct-99" / name))
+
+
+if __name__ == "__main__":
+    unittest.main()

package/tests/test_codex_config_edit.py

@@ -0,0 +1,82 @@
+"""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_feature_and_profile_overrides_are_rejected(self):
+        for source in ('[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_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,130 @@
+"""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('[features.multi_agent_v2]\nmax_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_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"