simplify goal-loop executor binding; add sandbox container placeholder

Author: Forge

README.md

@@ -90,7 +90,7 @@ Execution flow dialog with mode and model selection:
 ## Features
 
 - **Plans** — architect produces marked plans that are auto-captured to SQL storage
-- **Execution** — `New session`, `Execute here`, and `Loop` launch paths for approved plans; loops can also target a configured remote opencode server (see [Configuration](docs/configuration.md#remotes))
+- **Execution** — approved-plan launch paths plus direct `/execute-goal` loops in dedicated worktree sessions; plan loops can also target a configured remote opencode server (see [Configuration](docs/configuration.md#remotes))
 - **Loops** — iterative coding/auditing with isolated git worktree and optional Docker sandbox
 - **Review Findings** — persistent, loop-scoped review findings across loop sessions
 - **TUI** — sidebar and execution dialog
@@ -122,14 +122,15 @@ Forge provides these tool groups:
 
 - **Plan tools** — `plan-read`, `section-read`
 - **Review tools** — `review-write`, `review-read`, `review-delete`
-- **Loop tools** — `execute-plan`, `loop-cancel`, `loop-status`
+- **Loop tools** — `execute-plan`, `execute-goal`, `loop-cancel`, `loop-status`
 - **Sandbox shell** — `sh` when a sandbox manager is available
 
 Loops always run in an isolated git worktree; Docker sandbox is used automatically when available.
 
 | Tool | Description |
 |------|-------------|
 | `execute-plan` | Execute a plan using an iterative development loop in an isolated git worktree, or `mode: new-session` to launch it in a fresh standalone session. Args: `title` required; `plan`, `loopName`, `hostSessionId`, `mode` optional. |
+| `execute-goal` | Execute a free-text goal in rotating dedicated code and auditor sessions inside an isolated git worktree. Args: `goal` required; `title`, `loopName`, `maxIterations`, `hostSessionId` optional. |
 | `loop-cancel` | Cancel an active loop by worktree name |
 | `loop-status` | List active/recent loops or get detailed status by worktree name, including cumulative token usage when available. Supports `restart=true` to restart any non-completed loop (`running`, `cancelled`, `errored`, `stalled`). Completed loops are history-only and cannot be restarted. |
 
@@ -142,6 +143,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | `/review` | Run a code review on current changes | auditor (subtask) |
 | `/review-plan` | Review a completed implementation against its original plan | auditor (subtask) |
 | `/execute-plan` | Start an iterative development loop in a worktree (or a fresh session with `mode: new-session`) | code |
+| `/execute-goal` | Execute a free-text goal in dedicated worktree sessions until an audit leaves no findings | code |
 | `/loop-status` | Check status of all active loops | code |
 | `/loop-cancel` | Cancel the active loop | code |
 
@@ -490,6 +492,10 @@ Symptoms include:
 
 The flag must be set before OpenCode starts — setting it inside an already-running session is too late. If OpenCode is launched by a desktop app, service manager, shell alias, terminal profile, or wrapper script, set the variable there and fully restart OpenCode.
 
+### Workspace prerequisites
+
+Worktree loops require a git repository with at least one commit. OpenCode scopes its instance to project `global` when started in a directory without a root commit, and worktree loop sessions created against a `global` project are invisible to the TUI. If you see a "No git commit in this project" error, create an initial commit and restart OpenCode.
+
 ## Docker Sandbox
 
 Run loop iterations inside an isolated Docker container. Sandbox is optional: when Docker is available and configured, Forge provisions a loop container automatically; otherwise loops run in worktree-only mode.

container/Dockerfile

@@ -69,6 +69,25 @@ RUN useradd -m -u 1000 forge \
 RUN corepack pnpm add -g fallow@2.101.0 --global-bin-dir /usr/local/bin \
     && chmod -R 0777 /home/forge
 
+# --- Optional: in-container browser testing (Chromium + Chrome DevTools MCP) ---
+# Lets loops drive a browser inside the sandbox against dev servers that also run
+# inside the sandbox (shared network namespace, plain localhost) with zero host
+# exposure. Opt-in per project via `loop.worktreeOpencodeConfig`; see
+# docs/sandbox.md "Browser testing". Delete this whole block to build a slimmer
+# image without browser support.
+#
+# Debian's chromium package is used because Google Chrome ships no linux/arm64
+# build (Apple Silicon hosts run linux/arm64 containers). The trailing chmod
+# re-asserts store permissions after a root pnpm install — see the fallow note
+# above; it applies to every root pnpm step.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        chromium \
+        fonts-liberation \
+    && rm -rf /var/lib/apt/lists/*
+RUN corepack pnpm add -g chrome-devtools-mcp@1.5.0 --global-bin-dir /usr/local/bin \
+    && chmod -R 0777 /home/forge
+# --- End optional browser testing block ---
+
 # Docker Engine (daemon + CLI + buildx + compose) from Docker's official apt
 # repository. This enables Docker-in-Docker: when the container is launched with
 # FORGE_DIND=1 (privileged), the entrypoint starts a nested, isolated dockerd so

docs/agents-and-commands.md

@@ -41,7 +41,7 @@ Source: [`AUDITOR_TOOL_EXCLUDES`](../src/agents/auditor.ts).
 | `/review` | Run a code review. | `auditor` | yes |
 | `/review-plan` | Review a completed implementation against its original plan. | `auditor` | yes |
 | `/execute-plan` | Start an iterative development loop in a worktree (or launch the plan in a fresh standalone session with `mode: new-session`). | `code` | no |
-| `/execute-goal` | Execute a goal directly in the invoking session inside an isolated worktree, with fresh auditor sessions until no findings remain. | `code` | no |
+| `/execute-goal` | Execute a goal in rotating dedicated code and auditor sessions inside an isolated worktree. | `code` | no |
 | `/loop-status` | Check status of all active loops. | `code` | no |
 | `/loop-cancel` | Cancel the active loop. | `code` | no |
 

docs/api/README.md

@@ -93,7 +93,7 @@ Execution flow dialog with mode and model selection:
 ## Features
 
 - **Plans** — architect produces marked plans that are auto-captured to SQL storage
-- **Execution** — approved-plan launch paths plus direct `/execute-goal` work in the invoking session; plan loops can also target a configured remote opencode server (see [Configuration](_media/configuration.md#remotes))
+- **Execution** — approved-plan launch paths plus direct `/execute-goal` loops in dedicated worktree sessions; plan loops can also target a configured remote opencode server (see [Configuration](_media/configuration.md#remotes))
 - **Loops** — iterative coding/auditing with isolated git worktree and optional Docker sandbox
 - **Review Findings** — persistent, loop-scoped review findings across loop sessions
 - **TUI** — sidebar and execution dialog
@@ -132,7 +132,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | Tool | Description |
 |------|-------------|
 | `execute-plan` | Execute a plan using an iterative development loop in an isolated git worktree, or `mode: new-session` to launch it in a fresh standalone session. Args: `title` required; `plan`, `loopName`, `hostSessionId`, `mode` optional. |
-| `execute-goal` | Execute a non-empty goal in the invoking session inside an isolated worktree. Fresh auditors run on idle until no findings remain. |
+| `execute-goal` | Execute a free-text goal in rotating dedicated code and auditor sessions inside an isolated git worktree. Args: `goal` required; `title`, `loopName`, `maxIterations`, `hostSessionId` optional. |
 | `loop-cancel` | Cancel an active loop by worktree name |
 | `loop-status` | List active/recent loops or get detailed status by worktree name, including cumulative token usage when available. Supports `restart=true` to restart any non-completed loop (`running`, `cancelled`, `errored`, `stalled`). Completed loops are history-only and cannot be restarted. |
 
@@ -145,7 +145,7 @@ Loops always run in an isolated git worktree; Docker sandbox is used automatical
 | `/review` | Run a code review on current changes | auditor (subtask) |
 | `/review-plan` | Review a completed implementation against its original plan | auditor (subtask) |
 | `/execute-plan` | Start an iterative development loop in a worktree (or a fresh session with `mode: new-session`) | code |
-| `/execute-goal` | Execute a goal directly in the invoking session inside a managed worktree loop | code |
+| `/execute-goal` | Execute a free-text goal in dedicated worktree sessions until an audit leaves no findings | code |
 | `/loop-status` | Check status of all active loops | code |
 | `/loop-cancel` | Cancel the active loop | code |
 
@@ -494,6 +494,10 @@ Symptoms include:
 
 The flag must be set before OpenCode starts — setting it inside an already-running session is too late. If OpenCode is launched by a desktop app, service manager, shell alias, terminal profile, or wrapper script, set the variable there and fully restart OpenCode.
 
+### Workspace prerequisites
+
+Worktree loops require a git repository with at least one commit. OpenCode scopes its instance to project `global` when started in a directory without a root commit, and worktree loop sessions created against a `global` project are invisible to the TUI. If you see a "No git commit in this project" error, create an initial commit and restart OpenCode.
+
 ## Docker Sandbox
 
 Run loop iterations inside an isolated Docker container. Sandbox is optional: when Docker is available and configured, Forge provisions a loop container automatically; otherwise loops run in worktree-only mode.
@@ -503,6 +507,7 @@ See [Sandbox](_media/sandbox.md) for setup, Docker-in-Docker behavior, host netw
 ### Prerequisites
 
 - Docker running on your machine
+- OpenCode >= 1.15.5 — sandbox shell routing relies on the session-aware `shell.env` plugin hook. Enforced via `engines.opencode`, so older versions refuse to load the plugin rather than silently running sandbox commands on the host. (Loops additionally require OpenCode >= 1.17.8 for workspace integration, see [Requirements](#requirements).)
 
 ### Setup
 

docs/api/_media/agents-and-commands.md

@@ -41,7 +41,7 @@ Source: [`AUDITOR_TOOL_EXCLUDES`](../src/agents/auditor.ts).
 | `/review` | Run a code review. | `auditor` | yes |
 | `/review-plan` | Review a completed implementation against its original plan. | `auditor` | yes |
 | `/execute-plan` | Start an iterative development loop in a worktree (or launch the plan in a fresh standalone session with `mode: new-session`). | `code` | no |
-| `/execute-goal` | Execute a goal directly in the invoking session inside an isolated worktree, with fresh auditor sessions until no findings remain. | `code` | no |
+| `/execute-goal` | Execute a goal in rotating dedicated code and auditor sessions inside an isolated worktree. | `code` | no |
 | `/loop-status` | Check status of all active loops. | `code` | no |
 | `/loop-cancel` | Cancel the active loop. | `code` | no |
 

docs/api/_media/configuration.md

@@ -100,9 +100,10 @@ The written file is added to the worktree's git exclude so it never appears in `
 
 Notes:
 - The written file is ephemeral. Forge deletes its own `opencode.jsonc` before any teardown commit (and the whole worktree is removed on completion), so it can never land in loop history — even if the git-exclude write failed. A repository-tracked `opencode.jsonc` is never deleted (forge did not write it). Because the file is removed at teardown, a restarted loop is rewritten from the current `loop.worktreeOpencodeConfig`, so edits take effect on the next run.
-- MCP servers declared here run as **host** processes from the worktree directory. When [Sandbox](sandbox.md) is enabled, only `bash`/`glob`/`grep` execute inside the container; the MCP commands themselves are not container-isolated.
+- MCP servers declared here run as **host** processes from the worktree directory. When [Sandbox](sandbox.md) is enabled, only `bash`/`glob`/`grep` execute inside the container; the MCP commands themselves are not container-isolated. To run an MCP server *inside* the loop's sandbox container, use the placeholder below with a `docker exec -i` command.
+- The string `{{FORGE_SANDBOX_CONTAINER}}` in any config value is replaced with the loop's sandbox container name (`forge-<loop>`) when the file is written. For loops without a sandbox, `mcp` entries referencing the placeholder are dropped instead, so the same config works with and without the sandbox.
 
-Example — expose Chrome DevTools MCP inside every loop:
+Example — Chrome DevTools MCP running inside the loop's sandbox container (Chromium and `chrome-devtools-mcp` ship preinstalled in the sandbox image; see [Sandbox › Browser Testing](sandbox.md#browser-testing)):
 
 ```jsonc
 {
@@ -111,7 +112,12 @@ Example — expose Chrome DevTools MCP inside every loop:
       "mcp": {
         "chrome-devtools": {
           "type": "local",
-          "command": ["npx", "chrome-devtools-mcp@latest", "--isolated"],
+          "command": [
+            "docker", "exec", "-i", "{{FORGE_SANDBOX_CONTAINER}}",
+            "chrome-devtools-mcp", "--headless", "--isolated",
+            "--executablePath=/usr/bin/chromium",
+            "--chromeArg=--no-sandbox", "--chromeArg=--disable-dev-shm-usage"
+          ],
           "enabled": true
         }
       }
@@ -120,6 +126,8 @@ Example — expose Chrome DevTools MCP inside every loop:
 }
 ```
 
+Without the sandbox, a host-side server works too (Chrome runs on the host and cannot reach in-container dev servers): `"command": ["npx", "chrome-devtools-mcp@latest", "--isolated"]`.
+
 ## Group Launch
 
 `groupLaunch` configures parallel feature orchestration (see the [`launch-group`](tools.md#group-tools) tool).