symphony-orchestrator 0.2.5 → 0.2.7

package/README.md

@@ -56,6 +56,13 @@ Edit `.symphony/settings.json` to choose an Issue Tracker, set tracker-specific
 status states, and set runtime commands. Runtime Settings reference secrets by environment variable
 name; secret values belong only in the Local Environment.
 
+When `.symphony/settings.json` is missing, Bootstrap seeds it with normal Runtime Settings from a
+local, allowlisted Agent Harness detection pass. The output names a selected Agent Harness when one is
+usable, reports when no supported usable Agent Harness was found, or says that
+existing Runtime Settings are preserved on repeated Bootstrap. Existing settings are preserved without
+regeneration. This adaptive missing-settings Bootstrap is onboarding guidance only: runtime readiness
+remains the dispatch authority before any agent work starts.
+
 ### Default Terminal Console
 
 Run `symphony` from the Workspace Repository root to start the default read-first Terminal Console.
@@ -65,11 +72,14 @@ and Task Branch context.
 Compozy PRD Run progress appears when Compozy tracking is selected.
 
 The Terminal Console is safe to keep open while Symphony runs. Its MVP safe local aids are limited to
-refreshing the latest in-memory Runtime State snapshot, navigating and filtering tabs, showing the
-Web Dashboard handoff command, and inspecting validated local paths such as the Workspace Repository
-or Runtime Home. These aids do not retry tasks, pause or resume dispatch, update tracker status, merge
-or push Task Branches, open pull requests, change Runtime Contract files, or otherwise mutate task
-lifecycle state.
+refreshing the latest in-memory Runtime State snapshot, navigating and filtering tabs, opening focused Terminal Console settings with `s`, starting or reusing the loopback Web Dashboard with `w`, and inspecting validated local paths such as the Workspace Repository or Runtime Home.
+
+The `s` settings surface persists Terminal Console theme in ignored Runtime Home state and persists the
+Web Dashboard port by updating only Runtime Settings `server.port`. It is not a general Runtime
+Settings editor and does not edit `server.host`, tracker, Git, agent, Harness, Sandbox, queue, or
+lifecycle settings. The `w` action starts or reuses a compatible loopback Web Dashboard for the current
+Workspace Repository and Runtime Home, then shows the dashboard URL. If the configured port is occupied
+by an incompatible listener, Symphony reports a conflict instead of attaching to it. Settings and `w` do not retry tasks, pause or resume dispatch, update tracker status, merge or push Task Branches, open pull requests, or otherwise mutate task lifecycle state.
 
 Use Web Dashboard mode when browser-level inspection is more useful:
 
@@ -78,7 +88,9 @@ symphony --web --port 8080
 ```
 
 The Web Dashboard keeps using the Live Dashboard Connection as a Runtime State stream. It is not a
-Terminal Console command channel.
+Terminal Console command channel. Terminal Console V1 dashboard controls are loopback-only; non-loopback
+Web Dashboard access remains an explicit Runtime Settings choice and continues to require the
+server-generated local dashboard auth token for Runtime State HTTP and Live Dashboard Connection access.
 
 For a non-interactive check, use `symphony --once`; it prints terminal output and exits without
 starting the foreground Terminal Console loop.
@@ -261,6 +273,22 @@ reasoning, and timeout fields for planner, engineer, or reviewer work:
         "command": ""
       }
     },
+    "cursor": {
+      "kind": "cursor",
+      "command": "cursor-agent -p --model <model> --output-format stream-json",
+      "loop": {
+        "enabled": false,
+        "command": ""
+      }
+    },
+    "cursor-force": {
+      "kind": "cursor",
+      "command": "cursor-agent -p --force --model <model> --output-format stream-json",
+      "loop": {
+        "enabled": false,
+        "command": ""
+      }
+    },
     "pi": {
       "kind": "pi",
       "command": "pi --model <model> --thinking <reasoning> --print --no-session",
@@ -308,12 +336,26 @@ reasoning, and timeout fields for planner, engineer, or reviewer work:
 }
 ```
 
-PI and Claude are not prerequisites for Codex-only dispatch. Symphony validates install and
+PI, Claude, and Cursor are not prerequisites for Codex-only dispatch. Symphony validates install and
 authentication readiness only for Harnesses selected by enabled Stage Agent routes. A selected PI
 Harness requires the `pi` executable on `PATH` and provider authentication for the configured model. A
 selected Claude Harness requires the `claude` executable and Claude Code authentication, such as
-`ANTHROPIC_API_KEY` or Claude's configured login state. Runtime Settings must reference only
-environment variable names, never secret values.
+`ANTHROPIC_API_KEY` or Claude's configured login state. A selected Cursor Harness requires the
+`cursor-agent` executable and a successful `cursor-agent status` check, using either browser login or
+`CURSOR_API_KEY`. Use the non-`--force` Cursor Harness for review-first operation; select the
+`cursor-force` Harness only when the `Workspace Repository` operator intentionally wants Cursor to
+write directly during that role. Runtime Settings must reference only environment variable names,
+never secret values.
+
+To assign Cursor to any Logical Agent, set `agents.<name>.harness` to `cursor` or `cursor-force`.
+Keep `stageAgents.stages[]` routing by Logical Agent name rather than placing provider fields on the
+stage itself.
+
+Generated first-run Runtime Settings keep all supported Harness definitions available for editing. When
+Bootstrap detects a usable supported Harness, the default Logical Agents route to the selected Harness;
+when no Harness is usable, the default Logical Agent routes remain `codex`, `claude`, and `pi` so the
+next manual edit is explicit. Repeated Bootstrap preserves existing Runtime Contract files and does not
+reinterpret, regenerate, or rewrite Harness settings.
 
 Legacy settings that place Harness definitions under `agents.*`, such as `agents.pi.kind`, are
 migration input. When the new Runtime Settings shape is in use, Symphony reports a blocking Readiness
@@ -324,6 +366,44 @@ definitions. Stage-level `stageAgents.stages[].harness` is also legacy input; mo
 If setup is incomplete, the Terminal Console still starts and prints Readiness Gaps with remediation
 steps. Dispatch remains disabled until those gaps are resolved.
 
+### Optional Docker Sandbox
+
+Sandboxing is a repository-level Runtime Settings boundary for Workspace Repositories that should run
+agent work through Docker instead of direct host Agent Harness execution. It is optional and disabled
+by default. Docker is the only supported sandbox type in V1:
+
+```json
+{
+  "sandbox": {
+    "enabled": false,
+    "type": "docker",
+    "image": "ghcr.io/your-org/symphony-agent:latest",
+    "bootstrapCommands": [],
+    "persistent": true,
+    "networkEnabled": false,
+    "cpuLimit": 2,
+    "memoryMb": 4096
+  }
+}
+```
+
+Set `sandbox.enabled` to `true` only after replacing `sandbox.image` with the Docker image for the
+Workspace Repository. When sandboxing is enabled, Symphony treats the Sandbox as required for agent
+execution in that repository. Missing required settings, unsupported `sandbox.type` values, Docker
+availability problems, or unhealthy sandbox state are Readiness Gaps and block dispatch; Symphony does
+not silently fall back to host execution.
+
+`sandbox.bootstrapCommands` is a list of non-empty shell commands that run only when Symphony creates
+or recreates the Agent Worktree-scoped Docker container. V1 requires `sandbox.persistent: true` so
+restarts of the same work item can reuse the named container without sharing it with concurrent Agent
+Worktrees. `sandbox.networkEnabled` makes network access explicit, and `sandbox.cpuLimit` /
+`sandbox.memoryMb` must be positive integers.
+
+Runtime State snapshots include the running-work fields `sandbox_enabled`, `sandbox_provider`, and
+`sandbox_reuse_outcome`. The reuse outcome is one of `created`, `reused`, or `recreated`; these
+fields are the V1 visibility surface for confirming whether a sandboxed run used a fresh, warm, or
+refreshed container.
+
 For the GitHub Tracker, readiness includes the configured owner, Workspace Repository name, GitHub
 Project number, status field, and token environment variable. For Local Issue Tracker runs,
 GitHub owner, repo, Project, and token settings are not required. The local tracker readiness checks
@@ -473,8 +553,8 @@ from the same Compozy PRD Run when those files exist.
 Set `goal.enabled` to `true` on a specific stage to allow Stage Goal Handoff for that stage only.
 The selected Harness decides whether a loop command is actually sent. The Bootstrap default Codex
 Harness has `loop.enabled: true` and `loop.command: "/goal"`, so Codex receives `/goal` with
-deterministic Stage Goal Context before the normal Agent Prompt. The Bootstrap default Claude and PI
-Harnesses have loop disabled, so those Harnesses run the normal prompt even when a stage has
+deterministic Stage Goal Context before the normal Agent Prompt. The Bootstrap default Claude, Cursor,
+and PI Harnesses have loop disabled, so those Harnesses run the normal prompt even when a stage has
 `goal.enabled: true`. Stage Goal Context includes issue identifier, title, description, comments, URL,
 current tracker status, labels, priority when present, blocker references when present,
 attempt, and stage agent name. It omits issue creation and update timestamps.
@@ -490,6 +570,71 @@ goals = true
 If a selected loop-enabled Codex Harness cannot accept the configured loop command, Symphony reports a
 Readiness Gap. Goal Usage reported by Codex is stored in Runtime State for running, retrying, and
 attention-needed task details when available; missing or unparseable Goal Usage does not fail a task.
+If a selected loop-enabled Cursor Harness cannot accept the configured loop command from standard
+input, Symphony reports a Cursor loop Readiness Gap. Cursor `stream-json` activity updates the same
+running-task Runtime State fields used by other Harnesses, while raw stdout and stderr logs remain
+available as diagnostics.
+
+Goal Loop is separate from Stage Goal Handoff. Stage Goal Handoff is launch-time prompt handoff;
+Goal Loop is Runtime-owned Stage Agent behavior that can stop as Goal met, Needs attention, or
+Budget exhausted. Goal met requires deterministic evidence, so Goal Usage, agent exit `0`, changed
+files, or model confidence alone does not count as completion evidence.
+
+Enable Goal Loop per stage with `goalLoop`. Bootstrap does not add Goal Loop defaults; omitting the
+block keeps existing stage behavior unchanged. The `goalLoop.evidence` block configures the Goal
+Loop Evidence Command. The evidence command is an argv array, runs from the configured working
+directory, receives the same structured input on stdin and through the Context Command temp-file path
+convention, and should print a concise, secret-free evidence summary:
+
+```json
+{
+  "stageAgents": {
+    "enabled": true,
+    "root": ".symphony/agents",
+    "stages": [
+      {
+        "states": ["Todo", "To-Do", "In progress", "In Progress"],
+        "agent": "engineer",
+        "successStatus": "In review",
+        "retryStatus": "To-Do",
+        "goalLoop": {
+          "enabled": true,
+          "evidence": {
+            "command": ["pnpm", "test"],
+            "cwd": "agentWorktree",
+            "timeoutMs": 120000,
+            "maxOutputBytes": 8192
+          },
+          "budget": {
+            "maxTurns": 4,
+            "maxRuntimeMs": 3600000,
+            "maxTokens": 200000
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+The evidence command contract is intentionally narrow. A zero exit code with bounded stdout is
+successful deterministic evidence. Missing commands, timeouts, non-zero exits, invalid output, or
+missing deterministic evidence retry the same task with missing-evidence guidance while the
+configured budget allows another attempt; once the loop cannot continue, the stop outcome is Needs
+attention or Budget exhausted instead of Goal met.
+
+Runtime State exposes Goal Loop State as top-level `goal_loops[]` entries with `issue_id`,
+`issue_identifier`, `run_id`, `goal`, `state`, `stage_agent`, `harness_name`, `harness_kind`,
+`attempt_count`, `budget`, `latest_evidence`, `stop_outcome`, `stop_reason`, `next_action`,
+`diagnostics_path`, and `updated_at`. The Goal Loop Stop Outcome is `goal_met`, `needs_attention`, or
+`budget_exhausted`. The Terminal Console and Web Dashboard read that same Runtime State projection
+near Goal Usage and Context Status, including stopped Goal met, Needs attention, and Budget
+exhausted outcomes.
+
+Goal Loop does not own delivery authority. Stage Commit, Stage Push, Task Branch Integration, merge,
+pull request creation, auto-merge, and tracker status transitions stay governed by the existing
+Runtime Contract and run only through the existing completion and delivery lifecycle after Goal met
+evidence succeeds.
 
 Stage commits run after an agent exits successfully and before Symphony moves the issue to the
 stage's `successStatus`. Set `commit.enabled` per stage to control which transitions create commits;