ctrlrelay 0.24.0__tar.gz → 0.25.0__tar.gz

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/CHANGELOG.md

@@ -7,6 +7,36 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.0] - 2026-11-06
+
+### Fixed
+
+- A sandboxed run (`agent.sandbox: bwrap`) failed at once with "Argument
+  list too long" on a machine with thousands of past agent project folders
+  (#362). The sandbox mounted each `~/.claude/projects/*/memory` on its own,
+  which ran past both the kernel's argument limit and bwrap's 9000 arguments.
+  It now mounts `~/.claude/projects` read-only once, opens only the run's
+  own transcript folder for writing, and passes its options to bwrap
+  through a file descriptor. A config that lists the old glob in
+  `sandbox_readonly_paths` should drop it.
+
+### Added
+
+- `agent.max_parallel` lets one machine run several agents at once (#210).
+  It is one cap over new issues, resumed answers and the security sweep.
+  Each poll's issues start side by side up to the free slots, in priority
+  order, never two of one repo at once, and the loop polls again while they
+  run. Unset keeps the old one-at-a-time behaviour. The status page's slot
+  count now shows the real number of runs and the cap, or "no cap".
+- A dev run saves each step it finishes (plan, code, publish, verify) in a
+  new `run_steps` table, and a run whose process died is continued after
+  its last saved step instead of starting over (#231). The branch must
+  still be at the saved commit. The agent is not run again for a saved
+  code step, and a saved pull request is reused rather than opened twice.
+  Proof and review always run again. `ctrlrelay run dev --from-step
+  plan|code|publish` starts a new run from a past step, keeping the old
+  branch head under `refs/ctrlrelay/before-retry/`.
+
 ## [0.24.0] - 2026-11-05
 
 ### Added
@@ -2591,7 +2621,8 @@ pipeline).
   per-phase implementation plans (Phase 0 through Phase 4).
 - `docs/Claude_Code_Project_Guide.md` — project development guide.
 
-[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.24.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.25.0...HEAD
+[0.25.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.24.0...v0.25.0
 [0.24.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.23.0...v0.24.0
 [0.23.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.22.0...v0.23.0
 [0.22.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.21.0...v0.22.0

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.24.0
+Version: 0.25.0
 Summary: Local-first orchestrator for headless coding agents across multiple GitHub repos
 Project-URL: Homepage, https://github.com/AInvirion/ctrlrelay
 Project-URL: Documentation, https://ainvirion.github.io/ctrlrelay/

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/docs/cli.md

@@ -192,7 +192,7 @@ without waiting for a real pipeline run.
 ### `run dev`
 
 ```bash
-ctrlrelay run dev -i ISSUE [-r REPO] [-c PATH]
+ctrlrelay run dev -i ISSUE [-r REPO] [-c PATH] [--from-step STEP]
 ```
 
 | Flag | Required | Default | Description |
@@ -200,6 +200,7 @@ ctrlrelay run dev -i ISSUE [-r REPO] [-c PATH]
 | `--issue` / `-i` | yes | — | GitHub issue number. |
 | `--repo` / `-r` | when more than one repo is configured | — | Limit to a single `owner/repo`. |
 | `--config` / `-c` | no | `config/orchestrator.yaml` | Config path. |
+| `--from-step` | no | — | Start again from `plan`, `code` or `publish`, taking the earlier steps from the issue's newest run that saved them and moving the branch back. See [A run whose process died](operations.md#a-run-whose-process-died). |
 
 Acquires the per-repo lock, creates the worktree, spawns the repo's agent
 (Claude Code or OpenCode, per `agent.type` / `repos[].agent_type`) with the

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/docs/configuration.md

@@ -209,6 +209,7 @@ agent:
 | `type` | string | `"claude"` | Default backend for every repo: `"claude"` or `"opencode"`. See [agent backends](#agent-backends). |
 | `binary` | string | `"claude"` | Path to the `claude` executable. The bare name `"claude"` is auto-resolved at startup using `shutil.which("claude")`, then `~/.local/bin/claude`, `/usr/local/bin/claude`, `/opt/homebrew/bin/claude`. Set an absolute path to skip lookup (useful under launchd/systemd where PATH is minimal). |
 | `default_timeout_seconds` | int | `1800` | Per-session timeout passed to `asyncio.wait_for`. Sessions that exceed this are killed and reported as failed. A session going in circles is stopped before this; see [stuck runs](operations.md#stuck-runs). |
+| `max_parallel` | int (at least 1) | unset | How many agent runs this machine may have going at once, counted over new issues, resumed answers and the security sweep together. With it set, each poll's issues start side by side up to the free slots, in priority order, and never two of one repo at once; the poll loop polls again while they run. Unset keeps the old behaviour: new issues one at a time, and no shared limit. The status page shows `slots busy/max_parallel`, or `slots N (no cap)` when unset. See [running several agents at once](operations.md#running-several-agents-at-once). |
 | `output_format` | string | `"json"` | Not used. The relay always runs `claude -p --output-format stream-json --verbose`, because only that output carries the subscription usage it reads (see [usage](#usage)). Kept so existing configs still load. |
 
 ctrlrelay always invokes claude with `--dangerously-skip-permissions` so the
@@ -361,9 +362,10 @@ login, does not):
   snapshots, which your own sessions run or write back (the sandboxed run
   gets an empty, writable one of each);
 - read-only again, over those: `sandbox_readonly_paths` (the agent CLI's
-  settings, rules, hooks, plugins, skills, browser host and install, and each
-  project's memory under `~/.claude/projects/*/memory`, which your own
-  sessions load) and, in the repository, `config`, `config.worktree`,
+  settings, rules, hooks, plugins, skills, browser host and install, and the
+  whole `~/.claude/projects` folder with every project's memory, which your
+  own sessions load; only the run's own transcript folder in it is writable)
+  and, in the repository, `config`, `config.worktree`,
   `hooks`, `modules`, the other runs' worktree directories, a linked
   worktree's `commondir` and `gitdir`, and the worktree's `.git` pointer,
   which every later git command there reads. So the agent cannot change git
@@ -438,7 +440,7 @@ then run the check again. On a single-user laptop this is the whole setup.
 | `sandbox` | `"none"` or `"bwrap"` | `"none"` | `"bwrap"` runs the dev and task agents in the read-only sandbox above. |
 | `sandbox_hide_paths` | list of strings | `~/.ssh`, `~/.config/gh`, `~/.git-credentials`, `~/.config/git/credentials`, `~/.netrc`, `~/.local/share/keyrings`, `$XDG_RUNTIME_DIR/bus`, `~/.gnupg`, `~/.aws`, `~/.azure`, `~/.config/gcloud`, `~/.kube`, `~/.docker/config.json`, `~/.npmrc`, `~/.pypirc`, `~/.cargo/credentials`, `~/.cargo/credentials.toml`, `~/.config/doctl`, `~/.password-store`, `~/.1password`, `~/.docker/run`, `~/.docker/desktop`, `~/.config/ctrlrelay`, `$XDG_RUNTIME_DIR`, `/run/user/<uid>`, `/run/docker.sock`, `/var/run/docker.sock`, `~/.claude/shell-snapshots`, `~/.claude/session-env`, `~/.claude/ide`, `~/.claude/file-history` | Made empty under `sandbox: bwrap`. A directory becomes an empty tmpfs, a file or socket becomes `/dev/null`, a missing path is skipped. |
 | `sandbox_writable_paths` | list of strings | `~/.claude/*` | Writable under `sandbox: bwrap`, besides the run's own paths. A last part of `*` opens each entry in the directory now (not links), not the directory itself. |
-| `sandbox_readonly_paths` | list of strings | `~/.claude/settings.json`, `settings.local.json`, `CLAUDE.md`, `agents`, `commands`, `skills`, `hooks`, `plugins`, `output-styles`, `scripts`, `rules`, `chrome`, `local`, `projects/*/memory` (all under `~/.claude`) | Read-only again inside a writable path. One `*` part matches the directories there at the start of each run; a missing path under a writable one is created first (an empty `memory` directory in each project, for one). |
+| `sandbox_readonly_paths` | list of strings | `~/.claude/settings.json`, `settings.local.json`, `CLAUDE.md`, `agents`, `commands`, `skills`, `hooks`, `plugins`, `output-styles`, `scripts`, `rules`, `chrome`, `local`, `projects` (all under `~/.claude`) | Read-only again inside a writable path. One `*` part matches the directories there at the start of each run; a missing path under a writable one is created first. The run's own transcript folder under `projects` is made writable again by the relay. Before 0.25.0 the default had `projects/*/memory`, one mount per project folder; on a home with thousands of them bwrap could not start (#362). A config that still lists that glob has the same problem, so drop it. |
 | `sandbox_cache_dir` | string | `~/.ctrlrelay/agent-cache` | The agent's own package cache under `sandbox: bwrap`. |
 
 ## transport

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/docs/operations.md

@@ -781,6 +781,87 @@ limit until one is set.
   read. A run on `opencode` is not measured; with a limit set, the log gets
   `dispatcher.budget.unmeasured` and nothing is enforced.
 
+## A run whose process died
+
+A dev run saves each step it finishes: `plan`, `code`, `publish` and
+`verify` (#231). Each is a row in the `run_steps` table of the state DB,
+with the run branch's commit at that moment and what the later steps need
+(the plan, the agent's result, the pull request). No commit is added to the
+branch for it.
+
+When the relay process dies in the middle of a run (out of memory, a
+restart, a power cut), the poller settles that run when it starts again and
+hands the issue back. The next run for the issue then continues after the
+last saved step:
+
+- it checks that the branch is still at the saved commit, and starts from
+  the beginning if not (or stops with the reason, when the dead run had
+  already opened its pull request);
+- it does not run those steps again: no new agent session for a saved code
+  step, no second push or pull request for a saved publish step;
+- it comments on the issue which run it continues and from where;
+- `proof` and `review` always run again, because they read the pull
+  request as it is now.
+
+A dead run that had opened its pull request is handed back too, and only
+that pull request is reused. A run that failed for its own reasons is not
+continued; the next run starts from the beginning, as before.
+
+To start again from a past step by hand, for example to redo the code with
+the same plan:
+
+```bash
+ctrlrelay run dev --issue 42 --repo your-org/your-repo --from-step code
+```
+
+`--from-step` takes `plan`, `code` or `publish`, uses the newest run of the
+issue that saved steps, and moves the branch back to where it was before
+that step. The old head is kept at `refs/ctrlrelay/before-retry/<run id>`
+in the relay's clone. It refuses a branch behind an open pull request, and a
+branch that is on GitHub is synced back to GitHub's head; delete the remote
+branch first in that case.
+
+The log events are `dev.step.saved`, `dev.resume.restored` and
+`dev.resume.head_moved`.
+
+## Running several agents at once
+
+Set `agent.max_parallel` to let one machine run more than one agent (#210):
+
+```yaml
+agent:
+  max_parallel: 3
+```
+
+- **One cap over everything.** New issues from the poll, runs resumed after
+  you answer a question, and the scheduled security sweep all take a slot
+  from the same pool. A run takes its slot before the repo lock, and gives
+  it back when it ends.
+- **New issues side by side.** Polled issues wait in a backlog, in priority
+  order, and start as slots free up. Two issues of the same repo never run
+  together: the second waits, and an issue of another repo behind it goes
+  first. The loop keeps polling on its interval whatever is running, so one
+  slow issue never holds up new ones.
+- **A run holds its slot for its whole life**, including the wait for CI
+  and the fix rounds, and while it waits in the run for your answer. Once
+  it gives up waiting and saves the question, the slot is free again, and
+  the resume takes one when your answer comes. Two pull requests waiting on
+  slow CI can fill `max_parallel: 2`.
+- **A hold placed while a run waited for its slot is respected.** The resume
+  sweeper and the security sweep check again once they have a slot, so a
+  `self-update` that started meanwhile is not raced.
+- **On shutdown** no new run starts in a slot a stopping run frees, and
+  issues polled but not started are offered again after the restart.
+- **Unset** keeps the old behaviour: new issues one at a time, and nothing
+  limits the total.
+
+Each run uses its own agent session, worktree and memory. Size the number to
+the machine and to your plan's usage limits. Start with 2.
+
+The status page shows `slots busy/max`, and `slots N (no cap)` when it is
+unset. The log event `poll.batch.parallel` names each batch, the limit and
+how many slots were busy.
+
 ## When to restart
 
 | You changed... | Restart... |

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ctrlrelay"
-version = "0.24.0"
+version = "0.25.0"
 description = "Local-first orchestrator for headless coding agents across multiple GitHub repos"
 readme = "README.md"
 requires-python = ">=3.12"

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/src/ctrlrelay/cli.py

@@ -2503,6 +2503,16 @@ def run_dev(
         "-c",
         help="Path to orchestrator.yaml (default: auto-discover; see $CTRLRELAY_CONFIG).",
     ),
+    from_step: str | None = typer.Option(
+        None,
+        "--from-step",
+        help=(
+            "Start again from a past step of the issue's newest run that "
+            "saved steps: plan, code or publish. The steps before it are "
+            "taken from that run and the branch is moved back to where "
+            "it was then."
+        ),
+    ),
 ) -> None:
     """Run dev pipeline for a GitHub issue."""
     import asyncio
@@ -2598,6 +2608,7 @@ def run_dev(
             steps=repo_config.steps,
             question_on_issue=repo_config.question_on_issue,
             require_proof=repo_config.automation.require_proof,
+            from_step=from_step,
         )
 
     try:
@@ -3727,6 +3738,12 @@ def poller_start(
                         github, config.node_id,
                         window=sweep_window(config.schedules.secops_cron, config.timezone),
                     ),
+                    slots=agent_slots,
+                    # Asked again per repo once it has a slot (#210).
+                    held=lambda: (
+                        None if (h := intake_hold.active()) is None
+                        else h.reason
+                    ),
                 )
                 ok = sum(1 for r in results if r.success)
                 console.print(
@@ -3894,6 +3911,35 @@ def poller_start(
                 except Exception:
                     pass
 
+        # The node's cap on agent runs (#210), shared by the poll loop, the
+        # resume sweeper and the security sweep. No limit when unset.
+        from ctrlrelay.core.slots import AgentSlots
+        agent_slots = AgentSlots(config.agent.max_parallel)
+
+        def _resume_no_longer_wanted(row: dict) -> str | None:
+            """Why an answered question should not be resumed right now,
+            read after the wait for a slot (#210), or None to go ahead. A
+            hold placed meanwhile (a self-update) leaves the row for a
+            later tick; a row resumed, expired or answered again meanwhile
+            is not this tick's to run."""
+            hold = intake_hold.active()
+            if hold is not None:
+                return f"new work is held ({hold.reason})"
+            try:
+                current = state_db.get_pending_resume(row["session_id"])
+            except Exception as e:
+                # Could not look: leave the answer for the next tick rather
+                # than letting the sweeper's error path mark it resumed.
+                return f"the question could not be read ({type(e).__name__})"
+            if (
+                current is None
+                or current.get("resumed_at") is not None
+                or current.get("expired_at") is not None
+                or current.get("answered_at") != row.get("answered_at")
+            ):
+                return "the question is no longer waiting for this answer"
+            return None
+
         async def _run_pending_resume_sweeper() -> None:
             """Drain pending_resumes rows that an operator answered via
             Telegram while the original BLOCKED session had already torn
@@ -3998,28 +4044,40 @@ def poller_start(
                     try:
                         if pipeline_name == "secops":
                             sweep_repo_cfg = repo_cfg_by_name.get(repo)
-                            result = await resume_secops_from_pending(
-                                session_id=session_id,
-                                repo=repo,
-                                answer=answer,
-                                dispatcher=dispatcher,
-                                github=github,
-                                worktree=worktree,
-                                dashboard=scheduled_dashboard,
-                                state_db=state_db,
-                                transport=sweeper_transport,
-                                contexts_dir=config.paths.contexts,
-                                automation=(
-                                    sweep_repo_cfg.automation
-                                    if sweep_repo_cfg is not None
-                                    else None
-                                ),
-                                question=row.get("question"),
-                                # Same tracker as the poller and the
-                                # sweep: a repo archived while a session
-                                # sat blocked must not be resumed into.
-                                archived=poller.archived_tracker,
-                            )
+                            # A slot of the node's cap (#210), before the repo lock.
+                            async with agent_slots.hold():
+                                # The wait for a slot can be long (#210):
+                                # ask again whether to go ahead.
+                                gone = _resume_no_longer_wanted(row)
+                                if gone is not None:
+                                    console.print(
+                                        "[dim]pending_resume_sweeper: "
+                                        f"{session_id} not resumed now: "
+                                        f"{gone}[/dim]"
+                                    )
+                                    continue
+                                result = await resume_secops_from_pending(
+                                    session_id=session_id,
+                                    repo=repo,
+                                    answer=answer,
+                                    dispatcher=dispatcher,
+                                    github=github,
+                                    worktree=worktree,
+                                    dashboard=scheduled_dashboard,
+                                    state_db=state_db,
+                                    transport=sweeper_transport,
+                                    contexts_dir=config.paths.contexts,
+                                    automation=(
+                                        sweep_repo_cfg.automation
+                                        if sweep_repo_cfg is not None
+                                        else None
+                                    ),
+                                    question=row.get("question"),
+                                    # Same tracker as the poller and the
+                                    # sweep: a repo archived while a session
+                                    # sat blocked must not be resumed into.
+                                    archived=poller.archived_tracker,
+                                )
                         elif pipeline_name == "dev":
                             # Dev resume needs the repo's branch template
                             # to reconstruct the session's existing branch
@@ -4043,37 +4101,61 @@ def poller_start(
                                 except Exception:
                                     pass
                                 continue
-                            result = await resume_dev_from_pending(
-                                session_id=session_id,
-                                repo=repo,
-                                answer=answer,
-                                branch_template=repo_cfg.dev_branch_template,
-                                dispatcher=dispatcher,
-                                github=github,
-                                worktree=worktree,
-                                dashboard=scheduled_dashboard,
-                                state_db=state_db,
-                                transport=sweeper_transport,
-                                contexts_dir=config.paths.contexts,
-                                max_fix_attempts=repo_cfg.max_fix_attempts,
-                                code_review=repo_cfg.code_review,
-                                steps=repo_cfg.steps,
-                                question_on_issue=repo_cfg.question_on_issue,
-                                require_proof=repo_cfg.automation.require_proof,
-                            )
+                            # A slot of the node's cap (#210), before the repo lock.
+                            async with agent_slots.hold():
+                                # The wait for a slot can be long (#210):
+                                # ask again whether to go ahead.
+                                gone = _resume_no_longer_wanted(row)
+                                if gone is not None:
+                                    console.print(
+                                        "[dim]pending_resume_sweeper: "
+                                        f"{session_id} not resumed now: "
+                                        f"{gone}[/dim]"
+                                    )
+                                    continue
+                                result = await resume_dev_from_pending(
+                                    session_id=session_id,
+                                    repo=repo,
+                                    answer=answer,
+                                    branch_template=repo_cfg.dev_branch_template,
+                                    dispatcher=dispatcher,
+                                    github=github,
+                                    worktree=worktree,
+                                    dashboard=scheduled_dashboard,
+                                    state_db=state_db,
+                                    transport=sweeper_transport,
+                                    contexts_dir=config.paths.contexts,
+                                    max_fix_attempts=repo_cfg.max_fix_attempts,
+                                    code_review=repo_cfg.code_review,
+                                    steps=repo_cfg.steps,
+                                    question_on_issue=repo_cfg.question_on_issue,
+                                    require_proof=repo_cfg.automation.require_proof,
+                                )
                         elif pipeline_name == "task":
-                            result = await resume_task_from_pending(
-                                session_id=session_id,
-                                repo=repo,
-                                answer=answer,
-                                dispatcher=dispatcher,
-                                github=github,
-                                worktree=worktree,
-                                dashboard=scheduled_dashboard,
-                                state_db=state_db,
-                                transport=sweeper_transport,
-                                contexts_dir=config.paths.contexts,
-                            )
+                            # A slot of the node's cap (#210), before the repo lock.
+                            async with agent_slots.hold():
+                                # The wait for a slot can be long (#210):
+                                # ask again whether to go ahead.
+                                gone = _resume_no_longer_wanted(row)
+                                if gone is not None:
+                                    console.print(
+                                        "[dim]pending_resume_sweeper: "
+                                        f"{session_id} not resumed now: "
+                                        f"{gone}[/dim]"
+                                    )
+                                    continue
+                                result = await resume_task_from_pending(
+                                    session_id=session_id,
+                                    repo=repo,
+                                    answer=answer,
+                                    dispatcher=dispatcher,
+                                    github=github,
+                                    worktree=worktree,
+                                    dashboard=scheduled_dashboard,
+                                    state_db=state_db,
+                                    transport=sweeper_transport,
+                                    contexts_dir=config.paths.contexts,
+                                )
                         else:
                             console.print(
                                 "[yellow]pending_resume_sweeper: "
@@ -4498,6 +4580,7 @@ def poller_start(
                 await run_poll_loop(
                     poller=poller, handler=handle_issue_unless_held,
                     interval=interval,
+                    slots=agent_slots,
                     interval_scale=lambda: (
                         config.github_api.slow_factor
                         if github_budget.is_low() else 1.0

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/src/ctrlrelay/core/agent_env.py

@@ -244,9 +244,12 @@ DEFAULT_SANDBOX_READONLY_PATHS: tuple[str, ...] = (
     "~/.claude/chrome",
     # The agent CLI itself, when installed under its state directory.
     "~/.claude/local",
-    # Each project's memory, which the operator's sessions in that project
-    # load. One ``*`` part is expanded to the directories there now.
-    "~/.claude/projects/*/memory",
+    # Every project's folder, memory included, which the operator's
+    # sessions in that project load. One mount for all of them (#362): a
+    # mount per project folder ran past bwrap's argument limit on a home
+    # with thousands. The run's own transcript folder is opened again,
+    # deeper, by the dispatcher.
+    "~/.claude/projects",
 )
 
 # The agent's package caches: its own, never the operator's, so a run
@@ -285,6 +288,43 @@ def _existing(raw: str | Path) -> Path | None:
     return p if p.exists() else None
 
 
+def bwrap_args_via_fd(prefix: list[str]) -> tuple[list[str], int | None]:
+    """Move a ``bwrap_prefix`` argv's options into a file descriptor (#362).
+
+    One mount is a few path arguments, and a home with thousands of agent
+    project folders makes thousands of them: past ``ARG_MAX`` the kernel
+    refuses to start bwrap at all (``E2BIG``, "Argument list too long").
+    bwrap reads NUL-separated options from ``--args FD``, which has no such
+    limit, so the command line stays ``bwrap --args FD --`` however many
+    mounts there are.
+
+    Returns the short argv and the descriptor, which the caller passes to
+    the child (``pass_fds``) and closes once it has started. An empty
+    prefix (no sandbox) comes back as it is, with ``None``.
+    """
+    if not prefix:
+        return prefix, None
+    if prefix[-1] != "--":
+        raise ValueError("not a bwrap_prefix argv: it must end with '--'")
+    data = b"".join(os.fsencode(a) + b"\0" for a in prefix[1:-1])
+    if hasattr(os, "memfd_create"):
+        fd = os.memfd_create("ctrlrelay-bwrap-args")
+    else:  # pragma: no cover - bwrap is Linux-only, and Linux has memfd
+        import tempfile
+
+        fd, path = tempfile.mkstemp(prefix="ctrlrelay-bwrap-args-")
+        os.unlink(path)
+    try:
+        view = memoryview(data)
+        while view:
+            view = view[os.write(fd, view):]
+        os.lseek(fd, 0, os.SEEK_SET)
+    except BaseException:
+        os.close(fd)
+        raise
+    return [prefix[0], "--args", str(fd), "--"], fd
+
+
 def bwrap_prefix(
     bwrap: str,
     hide_paths: Sequence[str],

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/src/ctrlrelay/core/config.py

@@ -230,6 +230,11 @@ class AgentConfig(BaseModel):
     opencode: OpenCodeConfig = Field(default_factory=OpenCodeConfig)
     # #223. Off until a limit is set.
     budget: BudgetConfig = Field(default_factory=BudgetConfig)
+    # #210: how many agent runs this node may have going at once, over
+    # every track (new issues, resumed answers, the security sweep).
+    # Unset: no shared limit, and the poll loop takes one issue at a time,
+    # as before the setting existed.
+    max_parallel: int | None = Field(default=None, ge=1)
 
 
 # Backwards-compat alias. Older code and docs reference ``ClaudeConfig``;

{ctrlrelay-0.24.0 → ctrlrelay-0.25.0}/src/ctrlrelay/core/dispatcher.py

@@ -10,6 +10,7 @@ so pipelines can stay agent-agnostic.
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import json
 import os
 import re
@@ -29,6 +30,7 @@ from ctrlrelay.core.agent_env import (
     SandboxUnavailableError,
     agent_cache_env,
     build_agent_env,
+    bwrap_args_via_fd,
     bwrap_prefix,
     git_dirs,
     resolve_bwrap,
@@ -388,8 +390,15 @@ class CliAgentAdapter:
         repo: str | None,
         issue_number: int | None,
         budget_scope: BudgetScope | None = None,
+        sandbox_prefix_len: int = 0,
     ) -> SessionResult:
-        """Run the child built by :meth:`spawn_session` to completion."""
+        """Run the child built by :meth:`spawn_session` to completion.
+
+        The first ``sandbox_prefix_len`` items of ``cmd`` are the bwrap
+        prefix. Its options are moved into a file descriptor right before
+        the child starts, and closed right after (#362), so no error path
+        can leave the descriptor open.
+        """
 
         # The prompt can carry issue bodies and operator answers, so only its
         # hash and length are ever logged (#41).
@@ -424,13 +433,24 @@ class CliAgentAdapter:
             watches.append(("budget", budget.run))
 
         try:
-            proc = await asyncio.create_subprocess_exec(
-                *cmd,
-                cwd=working_dir,
-                env=env,
-                stdout=asyncio.subprocess.PIPE,
-                stderr=asyncio.subprocess.PIPE,
-            )
+            # The sandbox's options go through a file descriptor, not the
+            # command line, so no number of mounts can pass ARG_MAX (#362).
+            short, args_fd = bwrap_args_via_fd(cmd[:sandbox_prefix_len])
+            pass_fds = () if args_fd is None else (args_fd,)
+            try:
+                proc = await asyncio.create_subprocess_exec(
+                    *short, *cmd[sandbox_prefix_len:],
+                    cwd=working_dir,
+                    env=env,
+                    stdout=asyncio.subprocess.PIPE,
+                    stderr=asyncio.subprocess.PIPE,
+                    pass_fds=pass_fds,
+                )
+            finally:
+                # The child has its own copy now; bwrap reads it at start.
+                for fd in pass_fds:
+                    with contextlib.suppress(OSError):
+                        os.close(fd)
         except Exception as e:
             # Usually the binary isn't where we resolved it — the exception
             # propagates to the pipeline, but without this it lands there
@@ -886,12 +906,29 @@ class ClaudeDispatcher(CliAgentAdapter):
             copy.chmod(0o600)
             # At the real path: a bind on a link lands where it leads.
             copies.append((copy, Path(os.path.realpath(main_config))))
+        # Where the agent CLI writes this run's transcript: the only part
+        # of the read-only projects folder the run may write (#362). Made
+        # here, since the sandbox cannot create it under a read-only one.
+        transcript_dirs = self._transcript_dirs(working_dir, env)
+        projects = Path(os.path.realpath(Path.home() / ".claude" / "projects"))
+        for folder in transcript_dirs:
+            folder.mkdir(parents=True, exist_ok=True)
+            # Bound writable as it resolves: a link left there (a run before
+            # #362 could write the projects folder) would open its target,
+            # the home directory for one. Only a plain folder directly in
+            # `projects` is opened.
+            if folder.is_symlink() or Path(os.path.realpath(folder)).parent != projects:
+                raise SandboxUnavailableError(
+                    f"the transcript folder {folder} is a link or is not "
+                    f"directly in {projects}; remove it before running "
+                    "sandboxed"
+                )
         return bwrap_prefix(
             self._bwrap,
             self.sandbox_hide_paths,
             writable=[
                 working_dir, *repo_dirs, private_root, cache_dir,
-                *self.sandbox_writable_paths,
+                *self.sandbox_writable_paths, *transcript_dirs,
             ],
             readonly=[*self.sandbox_readonly_paths, *git_protected],
             copies=copies,
@@ -999,6 +1036,7 @@ class ClaudeDispatcher(CliAgentAdapter):
         self.started += 1
         try:
             return await self._run_session(
+                sandbox_prefix_len=len(prefix),
                 cmd=cmd,
                 env=env,
                 ident=ident,