orkestrator 2.22.3 → 2.24.0-alpha

package/README.md

@@ -1,11 +1,33 @@
 # Orkestrator backend and client
 
-The `orkestrator` executable has two modes:
+The `orkestrator` executable has three modes:
 
 - **Service** — `orkestrator`, `orkestrator serve …`, or the historical
   `orkestrator --host … --port …` forms run the backend in the foreground.
 - **Client** — `orkestrator <group> <command> …` talks to a backend that is
   already running. Client commands never start a backend.
+- **Problem report** — `orkestrator --fix AGENT` opens a coding agent to
+  collect diagnostics and draft a GitHub issue.
+
+## Reporting a problem
+
+Something wrong with Orkestrator? Let a coding agent help you report it:
+
+```bash
+bunx orkestrator --fix claude    # or codex, opencode
+```
+
+Instead of starting Orkestrator, this opens that agent's interactive session
+with instructions to ask what went wrong, read Orkestrator's logs and version
+details on this machine, and draft a GitHub issue for
+`orkestrator-ai/orkestrator-v2`. The agent is told to stay read-only, redact
+credentials and personal details, and file only after you approve the draft
+(through `gh`, or by giving you the new-issue link). It works in a new
+temporary directory and saves the draft there as `issue.md`.
+
+The agent on `PATH` is used; otherwise the copy Orkestrator installed. Pass
+`--data-dir DIR` when the backend uses a non-default data directory. Run
+`orkestrator --fix --help` for details.
 
 Run the Orkestrator backend service without installing the desktop application:
 
@@ -105,6 +127,7 @@ RUN_ID=$(jq -er '.result.runId' launch.json)
 SESSION=$(jq -er '.result.sessionId' launch.json)
 orkestrator run wait "$RUN_ID" --timeout 30m --json
 orkestrator session transcript "$SESSION" --limit 20 --json > transcript.json
+orkestrator changes view "$ENV" --json > changes.json
 orkestrator environment exec "$ENV" --wait -- bun test
 ```
 
@@ -146,5 +169,10 @@ fixture project/environment lifecycle through the installed client, confirms
 only one backend ran, and stops it. It needs network access, which is why it is
 a publish gate rather than part of `mise run test`.
 
+The npm dist-tag follows the version's update channel: `2.23.0` publishes as
+`latest`, `2.23.0-beta` as `beta` and `2.23.0-alpha` as `alpha`, so
+`bunx orkestrator` only ever gets a stable release. Try a prerelease with
+`bunx orkestrator@beta` or `bunx orkestrator@alpha`.
+
 `dist/client.js` is the client bundle the launcher imports first; it must stay
 free of backend imports so client commands never initialize a service.

package/bin/orkestrator.js

@@ -7,8 +7,8 @@ const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "
 const manifest = await Bun.file(path.join(packageRoot, "package.json")).json();
 const version = typeof manifest.version === "string" ? manifest.version : "0.0.0";
 
-// Decide service versus client before the backend is imported: help, version
-// and client commands must never initialize storage, listeners, or bridges.
+// Decide service versus client before the backend is imported: help, version,
+// --fix and client commands must never initialize storage, listeners, or bridges.
 const client = await import("../dist/client.js");
 const argv = process.argv.slice(2);
 const invocation = client.classifyInvocation(argv);
@@ -27,6 +27,9 @@ if (invocation.mode === "serve") {
   await import("../dist/main.js");
 } else if (invocation.mode === "client") {
   process.exitCode = await client.runClientProcess(invocation.argv, version);
+} else if (invocation.mode === "fix") {
+  // Opens a coding agent to help report a problem; no backend is started.
+  process.exitCode = await client.runFixProcess(invocation.argv, version);
 } else {
   process.exitCode = client.renderInvocationError(argv, invocation.message);
 }