@revisium/orchestrator 0.1.0-alpha.4 → 0.1.0-alpha.6

package/README.md

@@ -5,7 +5,7 @@ reviewer → integrator), hosted in **NestJS**. **DBOS** owns durable progress
 from the first unfinished step — while **Revisium** owns meaning: roles, policy, inbox, events. Workflow-as-data is
 a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overview.md).
 
-> 🚧 **Early alpha.** The end-to-end MVP works — `run create` → plan gate → implement → review → PR → merge
+> 🚧 **Early alpha.** The end-to-end MVP works — create a run → plan gate → implement → review → PR → merge
 > gate — see [`docs/roadmap.md`](./docs/roadmap.md).
 
 ## Start here
@@ -15,6 +15,154 @@ a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overv
 - Architecture & invariants: [`docs/architecture-overview.md`](./docs/architecture-overview.md)
 - Docs index & roadmap: [`docs/README.md`](./docs/README.md) · [`docs/roadmap.md`](./docs/roadmap.md)
 
+## Local Development
+
+`revo` is one daemonized product. **`revo start`** brings up the whole stack — the standalone
+Revisium daemon plus the Revo host daemon that owns DBOS and serves the GraphQL + MCP front doors —
+and bootstraps the control-plane so it is ready to use. The CLI is lifecycle-only
+(`start` / `stop` / `status` / `restart` / `doctor` / `logs`); orchestration (runs, inbox, …) is
+reached over **MCP** (agents) or **GraphQL** (UI/scripts), both served by the daemon.
+
+Run a source checkout alongside an installed package without collisions via a named **profile**
+(`--profile dev`, or `REVO_PROFILE=dev`): the `dev` profile shifts the whole port band off the
+`default` profile, so the two never share a port, data dir, or `dbos` database.
+
+```sh
+pnpm install
+pnpm run revo -- start --profile dev    # standalone + host daemon, bootstrapped & ready
+pnpm run revo -- status --profile dev   # stack health summary
+pnpm run revo -- doctor --profile dev   # diagnose process / port / profile issues
+pnpm run revo -- logs --profile dev     # tail host + standalone logs; add -f to follow
+pnpm run revo -- restart --profile dev  # stop, then start
+pnpm run revo -- stop --profile dev
+```
+
+| Knob | `default` (installed package) | `dev` (source checkout) |
+| --- | --- | --- |
+| data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
+| standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
+| Revo GraphQL | `19223` | `19623` |
+| DBOS database | `dbos` | `dbos_dev` |
+
+Any single knob can be overridden explicitly — `REVO_DATA_DIR` / `REVO_PORT` / `REVO_PG_PORT` /
+`REVO_GRAPHQL_PORT` / `REVO_DBOS_DB` — and an explicit env var always wins over the profile band.
+
+Connect an agent over MCP (a thin stdio bridge that forwards to the running daemon):
+
+```sh
+claude mcp add revo -- pnpm --dir "$PWD" run revo -- mcp
+```
+
+Run the local verification gates:
+
+```sh
+pnpm run typecheck
+pnpm run lint:ci
+pnpm run test:cov
+pnpm run verify
+```
+
+The smoke scripts are guarded: they require a non-default `REVO_DATA_DIR`,
+`REVO_PORT`, `REVO_PG_PORT`, and `REVO_DBOS_DB`; GraphQL smoke paths also require
+`REVO_GRAPHQL_PORT`.
+
+```sh
+pnpm run smoke:control-plane
+pnpm run smoke:create-run
+pnpm run smoke:inspect-run
+```
+
+### Live Run Observability Smoke
+
+This smoke runs a real agent. It can call provider CLIs and incur cost. Use it
+only when that is intentional.
+
+```sh
+export REVO_SMOKE_REPO=/path/to/local/sandbox-repo
+pnpm run revo -- start --profile dev   # standalone + host daemon (serves GraphQL + MCP), ready
+```
+
+Drive and observe a run through the daemon's front doors — there are no `run`/`serve` CLI commands.
+From an agent, use the MCP tools (`create_run`, `start_run`, then `get_agent_activity` /
+`get_agent_log`). From a UI or script, use the GraphQL front door the daemon already serves at
+`http://127.0.0.1:$REVO_GRAPHQL_PORT/graphql` — create a run:
+
+```graphql
+mutation Create($data: CreateRunInput!) {
+  createRun(data: $data) {
+    runId
+  }
+}
+```
+
+Then observe it over the same endpoint:
+
+```graphql
+query Activity($runId: ID!) {
+  runAgentActivity(runId: $runId) {
+    runId
+    aggregateStatus
+    latestOutputAt
+    attempts {
+      attemptId
+      runner
+      status
+      stdoutBytes
+      stderrBytes
+      artifactRef
+    }
+  }
+}
+
+query Log($data: GetAgentLogInput!) {
+  runAgentLog(data: $data) {
+    runId
+    attemptId
+    stream
+    offsetBytes
+    nextOffsetBytes
+    totalBytes
+    truncated
+    content
+  }
+}
+```
+
+For MCP, configure the MCP client to launch this checkout's local binary with the
+same environment. The MCP tools do not accept per-call profile arguments; the
+profile comes from the process environment.
+
+```json
+{
+  "mcpServers": {
+    "revo-dev": {
+      "command": "/path/to/agent-orchestrator/bin/revo.js",
+      "args": ["mcp"],
+      "env": {
+        "REVO_DATA_DIR": "/path/to/.revisium-orchestrator-dev",
+        "REVO_PORT": "19622",
+        "REVO_PG_PORT": "15840",
+        "REVO_GRAPHQL_PORT": "19623",
+        "REVO_DBOS_DB": "dbos_dev"
+      }
+    }
+  }
+}
+```
+
+Useful MCP observability tools for the same run:
+
+- `get_agent_activity`
+- `get_agent_attempts`
+- `get_agent_log`
+- `read_agent_output_events`
+- `tail_agent_log`
+
+If running from a sandboxed automation environment, local server checks may fail
+with `listen EPERM` or a misleading `No free port found from <port>`. Re-run the
+daemon, GraphQL, and MCP smoke commands from a normal terminal or an approved
+unsandboxed execution context.
+
 ## License
 
 See [LICENSE](./LICENSE).

package/control-plane/bootstrap.config.json

@@ -149,6 +149,7 @@
       "id": "steps",
       "schema": {
         "type": "object",
+        "description": "DEPRECATED/unused — runtime path retired (audit §3.1, #86); no live path writes or reads a steps row (DBOS owns progress). Table drop deferred — a schema drop on existing control-planes is riskier than retiring the writes; tracked in docs/roadmap.md → Post-MVP cleanup.",
         "additionalProperties": false,
         "properties": {
           "id": {

package/control-plane/default-playbook/catalog/pipelines.json

@@ -11,6 +11,7 @@
       "orchestrator",
       "analyst",
       "reviewer",
+      "triager",
       "developer",
       "integrator",
       "watcher"
@@ -36,7 +37,12 @@
             "approved",
             "clean",
             "blocker",
-            "changes_requested"
+            "changes_requested",
+            "review_changes",
+            "ci_changes",
+            "fix",
+            "wontfix",
+            "question"
           ]
         },
         "nodes": {
@@ -47,8 +53,12 @@
             "next": "planReviewer",
             "onFailure": "abort",
             "resultSchema": "schema:plan",
-            "produces": { "name": "plan" },
-            "incrementCounters": ["planReviewLoop"]
+            "produces": {
+              "name": "plan"
+            },
+            "incrementCounters": [
+              "planReviewLoop"
+            ]
           },
           "planReviewer": {
             "id": "planReviewer",
@@ -57,22 +67,43 @@
             "next": "planReviewRouter",
             "onFailure": "abort",
             "resultSchema": "schema:reviewVerdict",
-            "consumes": [{ "node": "analyst", "as": "plan" }]
+            "consumes": [
+              {
+                "node": "analyst",
+                "as": "plan"
+              }
+            ]
           },
           "planReviewRouter": {
             "id": "planReviewRouter",
             "kind": "choice",
             "branches": [
               {
-                "when": { "op": "verdict.in", "value": ["approved", "clean"] },
+                "when": {
+                  "op": "verdict.in",
+                  "value": [
+                    "approved",
+                    "clean"
+                  ]
+                },
                 "goto": "planGate"
               },
               {
                 "when": {
                   "op": "all",
                   "of": [
-                    { "op": "verdict.in", "value": ["blocker", "changes_requested"] },
-                    { "op": "counter.lt", "scope": "planReviewLoop", "value": 4 }
+                    {
+                      "op": "verdict.in",
+                      "value": [
+                        "blocker",
+                        "changes_requested"
+                      ]
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "planReviewLoop",
+                      "value": 4
+                    }
                   ]
                 },
                 "goto": "analyst"
@@ -109,7 +140,12 @@
             "next": "codeReview",
             "onFailure": "abort",
             "resultSchema": "schema:change",
-            "consumes": [{ "node": "analyst", "as": "plan" }]
+            "consumes": [
+              {
+                "node": "analyst",
+                "as": "plan"
+              }
+            ]
           },
           "codeReview": {
             "id": "codeReview",
@@ -173,7 +209,7 @@
             "id": "integrator",
             "kind": "script",
             "scriptRef": "script:integrator",
-            "next": "watcherPost",
+            "next": "pollPr",
             "catch": [
               {
                 "onError": "revo.ScriptBlocked",
@@ -187,70 +223,219 @@
             "onFailure": "route",
             "resultSchema": "schema:integration"
           },
-          "watcherPost": {
-            "id": "watcherPost",
-            "kind": "agent",
-            "roleRef": "role:watcher",
-            "next": "watcherRouter",
-            "onFailure": "abort",
-            "resultSchema": "schema:watchVerdict"
+          "mergeGate": {
+            "id": "mergeGate",
+            "kind": "humanGate",
+            "reason": "merge-review",
+            "outcomes": [
+              "approved"
+            ],
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "approved"
+                },
+                "goto": "confirmMerge"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
           },
-          "watcherRouter": {
-            "id": "watcherRouter",
+          "confirmMerge": {
+            "id": "confirmMerge",
+            "kind": "script",
+            "scriptRef": "script:confirmMerge",
+            "next": "mergedEnd",
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ],
+            "onFailure": "route",
+            "resultSchema": "schema:integration"
+          },
+          "mergedEnd": {
+            "id": "mergedEnd",
+            "kind": "terminal",
+            "status": "succeeded"
+          },
+          "failedEnd": {
+            "id": "failedEnd",
+            "kind": "terminal",
+            "status": "failed"
+          },
+          "blockedEnd": {
+            "id": "blockedEnd",
+            "kind": "terminal",
+            "status": "blocked"
+          },
+          "pollPr": {
+            "id": "pollPr",
+            "kind": "script",
+            "scriptRef": "script:pollPr",
+            "next": "prRouter",
+            "onFailure": "route",
+            "resultSchema": "schema:prFeedback",
+            "produces": {
+              "name": "prFeedback"
+            },
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ]
+          },
+          "prRouter": {
+            "id": "prRouter",
             "kind": "choice",
             "branches": [
               {
                 "when": {
-                  "op": "verdict.in",
-                  "value": [
-                    "approved",
-                    "clean"
-                  ]
+                  "op": "verdict.eq",
+                  "value": "clean"
                 },
                 "goto": "mergeGate"
               },
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "review_changes"
+                },
+                "goto": "triage"
+              },
               {
                 "when": {
                   "op": "all",
                   "of": [
                     {
-                      "op": "verdict.in",
-                      "value": [
-                        "blocker",
-                        "changes_requested"
-                      ]
+                      "op": "verdict.eq",
+                      "value": "ci_changes"
                     },
                     {
                       "op": "counter.lt",
-                      "scope": "watcherLoop",
+                      "scope": "ciLoop",
                       "value": 3
                     }
                   ]
                 },
-                "goto": "watcherRework"
+                "goto": "ciRework"
               },
               {
                 "default": "blockedEnd"
               }
             ]
           },
-          "watcherRework": {
-            "id": "watcherRework",
+          "ciRework": {
+            "id": "ciRework",
             "kind": "agent",
             "roleRef": "role:developer",
             "next": "integrator",
             "onFailure": "abort",
             "resultSchema": "schema:change",
             "incrementCounters": [
-              "watcherLoop"
+              "ciLoop"
+            ],
+            "consumes": [
+              {
+                "node": "pollPr",
+                "as": "feedback"
+              }
             ]
           },
-          "mergeGate": {
-            "id": "mergeGate",
+          "triage": {
+            "id": "triage",
+            "kind": "agent",
+            "roleRef": "role:triager",
+            "next": "triageRouter",
+            "onFailure": "abort",
+            "resultSchema": "schema:triage",
+            "produces": {
+              "name": "triage"
+            },
+            "consumes": [
+              {
+                "node": "analyst",
+                "as": "plan",
+                "staleOk": true
+              },
+              {
+                "node": "pollPr",
+                "as": "feedback"
+              }
+            ]
+          },
+          "triageRouter": {
+            "id": "triageRouter",
+            "kind": "choice",
+            "branches": [
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.eq",
+                      "value": "question"
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "questionLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "questionGate"
+              },
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.eq",
+                      "value": "fix"
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "reviewLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "reviewRework"
+              },
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "wontfix"
+                },
+                "goto": "respondThreads"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "questionGate": {
+            "id": "questionGate",
             "kind": "humanGate",
-            "reason": "merge-review",
+            "reason": "review-question",
             "outcomes": [
-              "approved"
+              "approved",
+              "changes_requested"
+            ],
+            "incrementCounters": [
+              "questionLoop"
             ],
             "branches": [
               {
@@ -258,30 +443,74 @@
                   "op": "verdict.eq",
                   "value": "approved"
                 },
-                "goto": "mergedEnd"
+                "goto": "triage"
               },
               {
                 "default": "blockedEnd"
               }
             ]
           },
-          "mergedEnd": {
-            "id": "mergedEnd",
-            "kind": "terminal",
-            "status": "succeeded"
+          "reviewRework": {
+            "id": "reviewRework",
+            "kind": "agent",
+            "roleRef": "role:developer",
+            "next": "reviewIntegrator",
+            "onFailure": "abort",
+            "resultSchema": "schema:change",
+            "incrementCounters": [
+              "reviewLoop"
+            ],
+            "consumes": [
+              {
+                "node": "triage",
+                "as": "triage"
+              }
+            ]
           },
-          "failedEnd": {
-            "id": "failedEnd",
-            "kind": "terminal",
-            "status": "failed"
+          "reviewIntegrator": {
+            "id": "reviewIntegrator",
+            "kind": "script",
+            "scriptRef": "script:integrator",
+            "next": "respondThreads",
+            "onFailure": "route",
+            "resultSchema": "schema:integration",
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ]
           },
-          "blockedEnd": {
-            "id": "blockedEnd",
-            "kind": "terminal",
-            "status": "blocked"
+          "respondThreads": {
+            "id": "respondThreads",
+            "kind": "script",
+            "scriptRef": "script:respondThreads",
+            "next": "pollPr",
+            "onFailure": "route",
+            "resultSchema": "schema:respond",
+            "consumes": [
+              {
+                "node": "triage",
+                "as": "triage"
+              }
+            ],
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ]
           }
         },
-        "title": "Feature development — plan + merge gates, bounded code-review + watcher rework",
+        "title": "Feature development — plan + merge gates, bounded code-review rework, and a PR review-feedback loop (plan 0018)",
         "policy": {
           "conflicts": [
             [
@@ -300,7 +529,15 @@
             "cap": 3,
             "parent": null
           },
-          "watcherLoop": {
+          "ciLoop": {
+            "cap": 3,
+            "parent": null
+          },
+          "reviewLoop": {
+            "cap": 3,
+            "parent": null
+          },
+          "questionLoop": {
             "cap": 3,
             "parent": null
           }

package/control-plane/default-playbook/catalog/roles.json

@@ -52,5 +52,14 @@
     "allowed_tools": ["Read", "Grep", "Glob", "Bash"],
     "default_model_level": "cheap",
     "runner_id": "claude-code"
+  },
+  {
+    "id": "triager",
+    "path": "prompts/triager.md",
+    "surface": "repo",
+    "rights": "read-only",
+    "allowed_tools": ["Read", "Grep", "Glob", "Bash"],
+    "default_model_level": "deep",
+    "runner_id": "claude-code"
   }
 ]

package/control-plane/default-playbook/prompts/analyst.md

@@ -18,7 +18,9 @@ reviewer can check against. The plan is the artifact a human approves at the pla
 
 ## Output
 
-Emit a structured plan. End your output with a single clear verdict token:
+Put the full ordered plan (problem, scope, files to change, steps, risks, verification) in the result
+`output` — the plan reviewer and the developer receive it verbatim as their input. Set the `verdict` field
+to EXACTLY one of:
 
 - `approved` — the task is well understood and the plan is ready for a developer.
 - `changes_requested` — the request is ambiguous or under-specified; explain what is missing.

package/control-plane/default-playbook/prompts/reviewer.md

@@ -19,10 +19,10 @@ are invoked in the pipeline.
 
 ## Output
 
-End your output with a single clear verdict token:
+Set the result `verdict` field (the pipeline routes on it) to EXACTLY one of these tokens:
 
 - `approved` — proceed; the work is correct and complete (nits are acceptable to defer).
 - `changes_requested` — fixable issues that must be addressed before proceeding.
 - `blocker` — a serious defect or risk that must be resolved (drives the bounded rework loop).
 
-Keep findings actionable. You are read-only: never modify the working tree.
+Put your actionable findings in `output`. You are read-only: never modify the working tree.