ctrlrelay 0.14.0__tar.gz → 0.15.0__tar.gz

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-10-31
+
+The dev and task agents no longer inherit the usual GitHub credentials;
+ctrlrelay does the pushing, PR opening and commenting itself
+after the agent exits. One new
+database table is added automatically and the new config values have
+defaults, so **no config edit is required** to upgrade.
+
+### Changed
+
+- Dev and task agents run with inherited `GH_*` and `GITHUB_*` variables
+  and gh's login removed from their environment, git credential helpers and
+  git's SSH disabled, and the D-Bus and runtime-dir variables pointed away
+  from the desktop keyring. After the agent exits the
+  relay pushes the run branch from a relay-private git dir to an explicit
+  GitHub URL, opens the PR from the DONE checkpoint (or reuses an open PR on the run
+  branch), pushes fix rounds,
+  fetches failed CI logs and posts task reports. It refuses to push the
+  default branch and only overwrites a remote branch whose head it recorded
+  pushing. secops keeps GitHub access (#235, closes #219)
+- Status page: the phase bar shows the furthest phase seen in the recent
+  transcript and pipeline events, CI waits are
+  shown as waiting rather than reading, and the PR is linked (#239, closes
+  #238)
+
+### Added
+
+- Optional `agent.sandbox: bwrap` with `agent.sandbox_hide_paths` to run the
+  dev and task agents under bubblewrap with credential paths hidden. Off by
+  default (#235)
+- A `relay_pushes` table recording the heads ctrlrelay pushed (#235)
+- Status page: a live counter and dot, server health, GitHub links, and the
+  list of skipped issues (#233, closes #232)
+
+### Known limits
+
+- The agent still runs as the same OS user. Without the bwrap sandbox it
+  can read credential files on disk; with it, only the paths in
+  `agent.sandbox_hide_paths` are hidden. It can still run ssh directly, reach
+  the Linux keyring by resetting the D-Bus address, or read a token kept
+  under some other variable name, and the macOS keychain is not covered. Running the agent as a separate user
+  is tracked in #236
+
 ## [0.14.0] - 2026-10-31
 
 A read-only status page. `state.db` switches to WAL mode and gains an
@@ -1796,7 +1839,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.14.0...HEAD
+[Unreleased]: https://github.com/AInvirion/ctrlrelay/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.14.0...v0.15.0
 [0.14.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.13.0...v0.14.0
 [0.13.0]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.4...v0.13.0
 [0.12.4]: https://github.com/AInvirion/ctrlrelay/compare/v0.12.2...v0.12.4

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ctrlrelay
-Version: 0.14.0
+Version: 0.15.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.14.0 → ctrlrelay-0.15.0}/docs/architecture.md

@@ -70,6 +70,14 @@ is the only place ctrlrelay calls out to Claude Code.
 - **Environment additions:** `CTRLRELAY_SESSION_ID` and `CTRLRELAY_STATE_FILE`
   are the only contract between dispatcher and child. Anything else the agent
   needs (issue body, PR rules, etc.) goes into the prompt.
+- **Credentials (#219):** every spawn says whether it gets GitHub access
+  (`spawn_session(..., github_access=...)`, no default). dev and task spawn
+  without it: GitHub tokens, `gh`'s login, git credential helpers, SSH and
+  the desktop keyring are cut off (`core/agent_env.py`), and ctrlrelay
+  pushes the branch, opens the PR or posts the report itself afterwards
+  (`core/publish.py`, `WorktreeManager.push_run_branch`). secops still
+  spawns with access. See
+  [What the agent can reach](configuration.md#what-the-agent-can-reach-219).
 - **Result:** `SessionResult(session_id, exit_code, state, stdout, stderr,
   agent_session_id)`. `session_id` is our composite orchestrator id;
   `agent_session_id` is Claude's own UUID, parsed from the JSON stdout and

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/docs/configuration.md

@@ -88,7 +88,78 @@ claude:
 
 ctrlrelay always invokes claude with `--dangerously-skip-permissions` so the
 agent does not pause on tool-permission prompts in headless runs. This is
-intentional — the orchestrator runs unattended.
+intentional — the orchestrator runs unattended. The CLI's other unattended
+modes either need every shell command allow-listed or filter by command text,
+which a wrapper script walks past, so they are not used as a guard. The guard
+is the next section: the agent holds no GitHub credentials.
+
+### What the agent can reach (#219)
+
+The dev and task agents run **without GitHub access**. ctrlrelay starts them
+with:
+
+- every `GH_*` and `GITHUB_*` variable removed (`GH_TOKEN`, `GITHUB_TOKEN`,
+  `GH_ENTERPRISE_TOKEN`, ...), and every inherited `CTRLRELAY_*` variable
+  (the chat bot tokens) except the two the checkpoint needs;
+- `GH_CONFIG_DIR` pointed at a fresh empty directory, so `gh` finds no login;
+- `DBUS_SESSION_BUS_ADDRESS` pointed at nothing, so `gh` and other libsecret
+  clients cannot fall back to the desktop keyring;
+- `credential.helper` reset to empty (through `GIT_CONFIG_COUNT`),
+  `GIT_SSH_COMMAND=false` and `SSH_AUTH_SOCK` removed, so git cannot
+  authenticate over HTTPS or SSH, including through an `insteadOf` rewrite;
+- `GIT_TERMINAL_PROMPT=0`, so nothing waits on a prompt.
+
+Everything else is inherited unchanged, so the model CLI and the project's
+toolchain behave as before. ctrlrelay then does the GitHub side itself, with
+its own credentials, after the agent exits:
+
+- **dev:** the agent commits on the run's branch and writes a PR title and
+  description in its DONE checkpoint. ctrlrelay pushes the branch and opens
+  the pull request. After a CI or conflict fix round it pushes again, and it
+  fetches the failed-job logs the agent used to read with `gh run view`.
+- **task:** the agent writes its report in its DONE checkpoint and ctrlrelay
+  posts it as the issue comment.
+- **secops** still runs **with** the operator's GitHub access. Its agent
+  reads Dependabot alerts and pull requests and merges what the policy
+  allows during the run. Moving it would mean ctrlrelay doing those reads
+  up front and the merges afterwards from a decision the agent returns.
+
+Pushes are refused, and logged as `publish.push.refused`, for `main`,
+`master`, the repository's default branch (read from the GitHub API, not
+from the local clone) and any branch that is not the run's own. The push
+goes to `https://github.com/<owner>/<repo>.git` (never `origin`) from a
+private git dir with hooks off and only ctrlrelay's own git config, pushes the
+commit it checked rather than the ref name, and uses `--force-with-lease`
+against the head this session last pushed (recorded in the state DB). An
+open PR found for the branch is reused only if its head repo is this repo and
+its base is the default branch. Text the agent wrote is posted with `@`-mentions and
+issue-closing keywords disabled and its length capped (20,000 characters);
+the PR's own `Closes #N` is added by ctrlrelay.
+
+**What this guarantees.** No GitHub credential is handed to the agent through
+its environment. ctrlrelay chooses the push URL, the branch and the PR base.
+`main`, `master`, the default branch and any branch other than the run's own
+are refused, and a branch that already exists on GitHub is only pushed over if
+its head is one ctrlrelay recorded pushing. Agent-written text is sanitized.
+An agent that only uses its normal tooling (git, gh, ssh as configured) cannot
+push. The push itself runs from a fresh relay-owned git dir under
+`~/.ctrlrelay/push/`, reads the clone's branch heads from its ref files, and
+never reads the clone's config, which every worktree shares.
+
+**What it does not guarantee.** The agent still runs as your user. A
+deliberately hostile agent can read `~/.config/gh/hosts.yml`, `~/.ssh` and
+anything else in your home directory and use them by hand; it can write
+anywhere your user can, including your dotfiles and ctrlrelay's install; and
+it can write to `~/.ctrlrelay/push/`, the bare clone's object store and any
+`objects/info/alternates` chain it adds there, racing a push. On macOS the
+login keychain is reachable whatever the environment says. Closing that needs
+a separate user or a read-only home (#236). The next setting hides the
+credential paths; it does not stop the writes.
+
+| Key | Type | Default | Description |
+|---|---|---|---|
+| `sandbox` | `"none"` or `"bwrap"` | `"none"` | `"bwrap"` runs the dev and task agents under bubblewrap with `sandbox_hide_paths` replaced by empty mounts. Linux only; needs `bwrap` installed and unprivileged user namespaces allowed (on Ubuntu 24.04+ an AppArmor profile for `bwrap`). ctrlrelay refuses to start if it is set and `bwrap` is missing. |
+| `sandbox_hide_paths` | list of strings | `~/.ssh`, `~/.config/gh`, `~/.git-credentials`, `~/.config/git/credentials`, `~/.netrc`, `~/.local/share/keyrings`, `$XDG_RUNTIME_DIR/bus` | Paths hidden under `sandbox: bwrap`. A directory becomes an empty tmpfs, a file or socket becomes `/dev/null`, a missing path is skipped. |
 
 ## transport
 
@@ -285,7 +356,7 @@ and ask the operator), or `never` (skip).
 | `exclude_labels` | `["manual", "operator", "instruction"]` | Issue labels that tell the poller "this isn't for the agent". See [exclude_labels](#reposautomationexclude_labels) below. |
 | `include_labels` | `[]` | Issue labels that opt an issue **into** the dev pipeline regardless of who is (or isn't) assigned. See [include_labels](#reposautomationinclude_labels) below. |
 | `require_labels` | `[]` | Issue labels that gate the plain-assignment trigger: when set, assignment alone is no longer enough — the issue must also carry one of these labels. See [require_labels](#reposautomationrequire_labels) below. |
-| `ci_wait_timeout_seconds` | `600` | Hard cap, in seconds, on the single `ctrlrelay ci wait` call the dev pipeline prompt tells Claude to run before signaling DONE. See [ci_wait_timeout_seconds](#reposautomationci_wait_timeout_seconds) below. |
+| `ci_wait_timeout_seconds` | `600` | Unused since #219 (the agent no longer waits on CI; ctrlrelay does). Still accepted so existing configs load. See [ci_wait_timeout_seconds](#reposautomationci_wait_timeout_seconds) below. |
 
 The current secops and dev pipelines read these settings to bias their prompts
 to Claude — they're not enforced by hard-coded checks.
@@ -432,7 +503,12 @@ repos:
 
 ### repos[].automation.ci_wait_timeout_seconds
 
-The dev pipeline prompt tells Claude to run `ctrlrelay ci wait --pr <PR>
+**Not used by the dev pipeline since #219.** The agent no longer has GitHub
+access, so it no longer waits on CI: ctrlrelay pushes the branch after the
+agent exits and its own PR verifier waits on CI. The key is still accepted so
+existing configs load. What follows describes the earlier behaviour.
+
+The dev pipeline prompt told Claude to run `ctrlrelay ci wait --pr <PR>
 --repo <repo> --timeout <N>` before signaling DONE — a single blocking call
 that polls GitHub every 15s until CI finishes, fails, or the timeout hits.
 No tokens get generated while it's blocked; on a repo with a slow CI suite,

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/docs/feedback-loop.md

@@ -151,9 +151,12 @@ Step-by-step:
 15–17. **Loop until terminal.** If the resumed session blocks again, steps
     8–14 repeat (capped at `DEFAULT_MAX_BLOCKED_ROUNDS`, currently 5). On
     `DONE`/`FAILED`, the loop exits.
-18. **PR verification.** If the dev pipeline got `DONE` with a `pr_url`, it
-    verifies the PR is mergeable and CI is green. If not, it asks Claude to
-    fix and re-verifies (up to `DEFAULT_MAX_FIX_ATTEMPTS`, currently 3).
+18. **Publish and verify.** On `DONE` the agent has only committed; it has
+    no GitHub access (#219). ctrlrelay pushes the run's branch, opens the PR
+    from the title and description in the checkpoint, then verifies the PR
+    is mergeable and CI is green. If not, it resumes the agent with the
+    failed-job logs, pushes the fix itself and re-verifies (up to
+    `DEFAULT_MAX_FIX_ATTEMPTS`, currently 3).
 19. **Operator notified.** The poller pushes a final `✅ PR ready: <url>` (or
     `❌ Failed: …`) message via the bridge.
 

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/docs/operations.md

@@ -238,10 +238,18 @@ journalctl --user -u ctrlrelay-poller -f
 ## Status page
 
 `ctrlrelay web start` serves a read-only page and JSON API showing what each
-agent is doing (phase, last command), what is waiting and why, the questions
-that need an answer, and a feed of what ctrlrelay did and said. It is a third
-process next to the bridge and the poller, so a slow or broken page can never
-stall them.
+agent is doing (phase, current activity, last command), what is waiting and
+why, the questions that need an answer, and a feed of what ctrlrelay did and
+said. It is a third process next to the bridge and the poller, so a slow or
+broken page can never stall them.
+
+On a running card, **phase** (the bar) is the furthest step the session has
+reached, from the agent's transcript plus ctrlrelay's own CI, review and PR
+events, so it never moves back. **Current activity** is the most recent step:
+an open CI wait or review if it started after the agent's latest step, else
+that step. It can be earlier than the bar, for example a read after the PR
+or a fix round after review. The card links the PR once ctrlrelay has
+recorded its number.
 
 It is **read-only**: it opens `state.db` read-only, reads the tail of each
 agent's transcript, and asks GitHub (through the `gh` login ctrlrelay already
@@ -257,6 +265,19 @@ loopback or on the home network.
 | `/api/status` | Everything on the page, as JSON (the contract is in `src/ctrlrelay/web/status.py`). A section that could not be read is `null` and `errors` says why; `[]` means "read, and empty". The feed holds at most the newest `feed_limit` (200) events: `feed_total` is how many the history window holds (`null` if unreadable) and `feed_truncated` is `true` when some were left out, in which case the page says "showing newest N of M". |
 | `/api/events?since=<epoch seconds>` | The feed, newest first, at most `limit` (200) events. Without `since`, the last `web.history_days` days. Carries the same `feed_total` and `feed_truncated`, plus the `limit` used. |
 
+The page header shows how long ago it last heard from the server ("updated
+12s ago", ticking every second) and a dot that is green while the last good
+answer is at most two refresh intervals old and red otherwise. Elapsed times
+on cards tick between polls too.
+
+Fields added in #232 (all in `/api/status`):
+
+| Field | What |
+|---|---|
+| `url` | On every `running`, `needs_you`, `waiting.items`, `skipped` and `feed` item (and on `/api/events` events): a link to the GitHub issue, or for a feed event that names a PR by number, the PR. Built only as `https://github.com/<owner>/<repo>/issues/<n>` or `/pull/<n>`, from a repo matching `owner/name` and an integer; `null` otherwise (a secops run with no issue, a restart). A `pr_url` an agent reported is never used. |
+| `skipped` | Every open issue assigned to you that the poller will **not** pick up and is not running, from the same search as the waiting line (no extra GitHub calls): `repo`, `issue_number`, `title`, `url`, `updated`/`updated_ts` and `reason`, one of `repo not in config`, `excluded label <label>`, `already handled once (won't retry)`, `missing required label <label>` (several joined with "or": any one admits it), `assigned by someone else`. `null` until GitHub has answered once; `waiting.status` and `waiting.last_good_ts` say how current it is. The page shows it collapsed, with a count. |
+| `server` | This machine's health, read on each request: `load_1m`, `load_5m`, `load_15m`, `cpu_count`, `memory` (`total_bytes`, `available_bytes`, `available_pct`, `low`), `disks` (one each for `home` and `worktrees`: `name`, `path`, `total_bytes`, `free_bytes`, `free_pct`, `low`), `uptime_s`, and `unavailable` (why any number is `null`; memory and uptime are `null` off Linux). `low` is true below 10% free and the page marks it. The whole section is `null`, with a line in `errors`, only if reading it failed outright. |
+
 Try it on loopback first (the default `web.host` is `127.0.0.1`, port `8787`):
 
 ```bash

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/docs/superpowers/specs/2026-10-30-status-page-design.md

@@ -117,15 +117,33 @@ pattern) and a timestamp. Phase is derived from the most recent tool uses:
 - `Read`, `Grep`, `Glob`, read-only shell (`cat`, `sed -n`, `grep`, `ls`, `git log/diff/show`) → **reading**
 - `Edit`, `Write`, `NotebookEdit` → **coding**
 - shell running a test runner (`pytest`, `npm test`, `npx playwright`, `go test`, `cargo test`, `uv run pytest`, ...) → **testing**
+- `ctrlrelay ci wait`, `gh pr checks`, `gh run watch`, `gh run view`, `gh pr view --json statusCheckRollup` → **CI**
 - `git push`, `gh pr create` → **PR**
 
+The bar shows the furthest phase reached (transcript tail plus pipeline events), so it
+never moves back; the card also names the current activity, which can be earlier (a
+read after the PR, a fix round after review) (#238).
+
 If no transcript is found, phase is **unknown**. The agents need no change for this.
 
 ### CI wait and review: ctrlrelay says when it starts and stops them
 
 After the agent exits, the dev pipeline waits for CI and runs the review itself. It
-writes an event when each starts and ends. While one is open for a session, that is
-the session's phase, and the card is not "looks stuck".
+writes an event when each starts and ends. While one is open for a session the card
+is not "looks stuck", and it is the session's current activity if it started after the
+agent's latest transcript step.
+
+### Phase and current activity (#238)
+
+- **phase** (the bar) is the furthest step reached, in the order reading < coding <
+  testing < CI < review < PR, over the transcript tail plus the session's pipeline
+  events (CI wait, review, PR opened). It never moves back, and it can come from
+  history: a CI wait that has finished still counts as reached.
+- **current_activity** is the most recent step by time: an open CI wait or review
+  when it started after the agent's latest transcript step, else that transcript
+  step, else unknown. It can be earlier than the bar (a read after the PR, a fix
+  round after review). `phase_source` says where it came from: `pipeline`,
+  `transcript`, or `none`.
 
 ### Waiting line: the web process asks GitHub (Oscar's choice)
 

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/pyproject.toml

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

ctrlrelay-0.15.0/src/ctrlrelay/core/agent_env.py

@@ -0,0 +1,228 @@
+"""What the coding agent's process is allowed to carry (#219).
+
+The relay runs the agent as the operator's own user, under the
+operator's own environment. Before #219 that environment reached the
+agent whole: a ``GH_TOKEN`` if one was set, ``SSH_AUTH_SOCK``, the
+chat bot tokens, and through them ``gh``'s stored login, git's
+credential helpers and the operator's SSH key. Text the agent reads
+(an issue body, a file in the repository) could therefore push to any
+branch or merge a pull request with the operator's login.
+
+For the dev and task lanes the relay now does every GitHub write
+itself, after the agent exits, so the agent needs none of that. This
+module builds the environment that says so:
+
+- GitHub token variables are removed, and so is everything else in
+  the ``GH_*`` and ``GITHUB_*`` families, because ``gh`` reads its
+  settings from the first and CI-style tooling reads tokens from the
+  second.
+- ``GH_CONFIG_DIR`` points at a fresh empty directory, so ``gh`` finds
+  no stored login.
+- git gets ``credential.helper`` reset to empty through
+  ``GIT_CONFIG_COUNT``, ``GIT_SSH_COMMAND=false`` so any SSH remote
+  (including one reached through an ``insteadOf`` rewrite, which is
+  how alkaturbo pushes) fails before a key is offered, and
+  ``GIT_TERMINAL_PROMPT=0`` so nothing waits on a prompt.
+- ``SSH_AUTH_SOCK`` and friends are removed.
+- The relay's own chat tokens are removed: the agent has no reason to
+  hold the credentials of the channel the operator is reached on.
+
+What it keeps is everything else, on purpose. The agent still has to
+run the model CLI (which authenticates from its own files under
+``~/.claude`` or from ``ANTHROPIC_*`` variables) and build and test
+the project with whatever toolchain the operator installed.
+
+What #219 guarantees: no GitHub credential is handed to the agent
+through its environment; ctrlrelay chooses the push URL, the branch and
+the base; main, master, the default branch and any other branch are
+refused; a remote branch ctrlrelay did not push is not overwritten;
+agent-written PR and comment text is sanitized; and an agent that only
+uses its normal tooling (git, gh, ssh as configured) cannot push.
+
+What it does NOT guarantee: the agent runs as the same OS user, so a
+deliberately hostile agent can still read credential files
+(``~/.config/gh/hosts.yml``, ``~/.ssh``), use them by hand, and write
+to the relay's push directory, the bare clone's object store and any
+``objects/info/alternates`` chain it adds there, racing a push. Closing
+that needs a separate user or a read-only home (#236). ``agent.sandbox:
+bwrap`` hides the credential paths; it does not stop the writes.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+# Named explicitly as well as caught by the prefix rule below, so the
+# list a reader greps for is in the file and a test can pin it.
+GITHUB_TOKEN_VARS: tuple[str, ...] = (
+    "GH_TOKEN",
+    "GITHUB_TOKEN",
+    "GH_ENTERPRISE_TOKEN",
+    "GITHUB_ENTERPRISE_TOKEN",
+)
+
+# Whole families, by prefix. ``gh`` reads GH_* (GH_HOST, GH_REPO,
+# GH_CONFIG_DIR, ...); GITHUB_* is where Actions-style tooling looks
+# for tokens. Nothing a build needs lives in either.
+_STRIPPED_PREFIXES: tuple[str, ...] = ("GH_", "GITHUB_")
+
+# Ways git or ssh could reach a credential without a token variable.
+# GIT_CONFIG_* is cleared so an inherited GIT_CONFIG_COUNT cannot
+# re-add a helper after ours (entries are numbered, and a second
+# count would replace ours wholesale). GIT_CONFIG_PARAMETERS is the
+# carrier for `git -c`, which outranks GIT_CONFIG_COUNT.
+_STRIPPED_EXACT: frozenset[str] = frozenset({
+    "SSH_AUTH_SOCK",
+    "SSH_AGENT_PID",
+    "SSH_ASKPASS",
+    "GIT_ASKPASS",
+    "GIT_SSH",
+    "GIT_SSH_COMMAND",
+    "GIT_CONFIG_PARAMETERS",
+    "GIT_CONFIG_COUNT",
+})
+_GIT_CONFIG_INDEXED = re.compile(r"^GIT_CONFIG_(KEY|VALUE)_\d+$")
+
+# The relay's own secrets. Every CTRLRELAY_* variable is dropped and
+# the two the checkpoint protocol needs are set again by the
+# dispatcher, so a chat token added later under a new name is covered
+# without anybody remembering to list it.
+_RELAY_PREFIX = "CTRLRELAY_"
+
+# Deliberately unconnectable. See build_agent_env.
+_NO_SESSION_BUS = "unix:path=/nonexistent/ctrlrelay-agent-has-no-session-bus"
+
+# Applied through GIT_CONFIG_COUNT. An empty `credential.helper`
+# resets the helper list, so helpers from ~/.gitconfig and from
+# /etc/gitconfig are never consulted.
+_GIT_CONFIG_OVERRIDES: tuple[tuple[str, str], ...] = (
+    ("credential.helper", ""),
+    ("core.askPass", ""),
+)
+
+
+def _is_stripped(name: str) -> bool:
+    if name in GITHUB_TOKEN_VARS or name in _STRIPPED_EXACT:
+        return True
+    if name.startswith(_STRIPPED_PREFIXES) or name.startswith(_RELAY_PREFIX):
+        return True
+    return bool(_GIT_CONFIG_INDEXED.match(name))
+
+
+def build_agent_env(
+    base: Mapping[str, str],
+    *,
+    gh_config_dir: Path,
+    runtime_dir: Path,
+) -> tuple[dict[str, str], list[str]]:
+    """Return ``(env, stripped_names)`` for an agent with no GitHub access.
+
+    ``gh_config_dir`` and ``runtime_dir`` must be empty directories the
+    agent did not choose; the caller creates and removes them.
+    ``runtime_dir`` becomes ``XDG_RUNTIME_DIR``, so a client that looks
+    for the session bus under it finds nothing there. ``stripped_names`` is
+    the sorted list of variable NAMES removed, for the log. Values
+    are never returned or logged.
+    """
+    env: dict[str, str] = {}
+    stripped: list[str] = []
+    for name, value in base.items():
+        if _is_stripped(name):
+            stripped.append(name)
+            continue
+        env[name] = value
+
+    env["GH_CONFIG_DIR"] = str(gh_config_dir)
+    # gh falls back to the desktop keyring (the Secret Service, over the
+    # D-Bus session bus) when its config dir has no token, and so does
+    # anything built on libsecret. Measured on a laptop host on
+    # 2026-10-31: with GH_CONFIG_DIR empty, `gh auth token` still printed
+    # the operator's token, with or without DBUS_SESSION_BUS_ADDRESS set,
+    # because the D-Bus client then dials /run/user/<uid>/bus by itself.
+    # An address that cannot connect is what stops it. macOS keeps the
+    # login keychain outside anything an environment variable reaches;
+    # see the configuration docs.
+    env["DBUS_SESSION_BUS_ADDRESS"] = _NO_SESSION_BUS
+    # Also replaced, so a client that derives the bus from it finds an
+    # empty private directory. Measured: gh's D-Bus client falls back to
+    # /run/user/<uid>/bus by uid when no address is set, ignoring this
+    # variable, so it is the address above that blocks that fallback;
+    # this closes the XDG-based one.
+    env["XDG_RUNTIME_DIR"] = str(runtime_dir)
+    env["GH_PROMPT_DISABLED"] = "1"
+    env["GIT_TERMINAL_PROMPT"] = "0"
+    env["GCM_INTERACTIVE"] = "never"
+    # `false` exits 1 without reading anything, so every SSH remote
+    # fails before a key or an agent is touched. Takes precedence over
+    # core.sshCommand in any config file.
+    env["GIT_SSH_COMMAND"] = "false"
+    env["GIT_CONFIG_COUNT"] = str(len(_GIT_CONFIG_OVERRIDES))
+    for i, (key, value) in enumerate(_GIT_CONFIG_OVERRIDES):
+        env[f"GIT_CONFIG_KEY_{i}"] = key
+        env[f"GIT_CONFIG_VALUE_{i}"] = value
+    return env, sorted(stripped)
+
+
+DEFAULT_SANDBOX_HIDE_PATHS: tuple[str, ...] = (
+    "~/.ssh",
+    "~/.config/gh",
+    "~/.git-credentials",
+    "~/.config/git/credentials",
+    "~/.netrc",
+    # The desktop keyring's files and the session bus it answers on,
+    # so resetting DBUS_SESSION_BUS_ADDRESS inside the sandbox does not
+    # reach it either.
+    "~/.local/share/keyrings",
+    "$XDG_RUNTIME_DIR/bus",
+)
+
+
+class SandboxUnavailableError(RuntimeError):
+    """``agent.sandbox: bwrap`` was configured and cannot be honoured."""
+
+
+def resolve_bwrap() -> str:
+    """Absolute path of ``bwrap``, or raise naming what was searched."""
+    found = shutil.which("bwrap")
+    if found:
+        return found
+    for candidate in ("/usr/bin/bwrap", "/usr/local/bin/bwrap"):
+        if os.access(candidate, os.X_OK):
+            return candidate
+    raise SandboxUnavailableError(
+        "agent.sandbox is 'bwrap' but no bwrap binary was found on PATH "
+        "or in /usr/bin, /usr/local/bin. Install bubblewrap or set "
+        "agent.sandbox: none."
+    )
+
+
+def bwrap_prefix(bwrap: str, hide_paths: Sequence[str]) -> list[str]:
+    """Argv prefix that runs a command with ``hide_paths`` made empty.
+
+    The rest of the filesystem is bound through unchanged and writable,
+    so the agent's toolchain, caches and the model CLI's own state
+    behave exactly as without the sandbox. Only the named paths change:
+    a directory becomes an empty tmpfs and a file becomes /dev/null.
+    A path that does not exist is skipped (bwrap would otherwise have
+    to create a mount point for it).
+    """
+    argv = [bwrap, "--dev-bind", "/", "/", "--die-with-parent"]
+    for raw in hide_paths:
+        expanded = os.path.expandvars(os.path.expanduser(raw))
+        if "$" in expanded:
+            # An unset variable: there is nothing at a path we cannot
+            # name, and a literal "$XDG_RUNTIME_DIR" is not a path.
+            continue
+        p = Path(expanded)
+        if p.is_symlink():
+            p = p.resolve()
+        if p.is_dir():
+            argv += ["--tmpfs", str(p)]
+        elif p.exists():
+            argv += ["--ro-bind", "/dev/null", str(p)]
+    argv.append("--")
+    return argv

{ctrlrelay-0.14.0 → ctrlrelay-0.15.0}/src/ctrlrelay/core/config.py

@@ -7,11 +7,13 @@ import re
 import socket
 from enum import Enum
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import yaml
 from pydantic import BaseModel, Field, field_validator, model_validator
 
+from ctrlrelay.core.agent_env import DEFAULT_SANDBOX_HIDE_PATHS
+
 CONFIG_FILENAME = "orchestrator.yaml"
 CONFIG_SUBDIR = "config"
 CONFIG_ENV_VAR = "CTRLRELAY_CONFIG"
@@ -83,6 +85,15 @@ class AgentConfig(BaseModel):
     binary: str = "claude"
     default_timeout_seconds: int = 1800
     output_format: str = "json"
+    # #219. "bwrap" runs the dev and task agents under bubblewrap with
+    # the paths below replaced by empty mounts, so the agent cannot
+    # read the SSH key or gh's stored login. Off by default because it
+    # needs bwrap installed and unprivileged user namespaces allowed.
+    # The credential stripping in core.agent_env applies either way.
+    sandbox: Literal["none", "bwrap"] = "none"
+    sandbox_hide_paths: list[str] = Field(
+        default_factory=lambda: list(DEFAULT_SANDBOX_HIDE_PATHS)
+    )
 
 
 # Backwards-compat alias. Older code and docs reference ``ClaudeConfig``;