@twin-build-orchestrate/cli 1.0.0-prerelease.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kei Yoshimoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+# @twin-build-orchestrate/cli
+
+Local orchestrator (dispatcher + agent worker) for the [twin-build](https://github.com/reality-xrcloud-inc/twin-build) framework.
+
+Runs on a developer's machine, polls the twin-build MCP server over HTTP, and dispatches agent workers to handle tickets autonomously. Does not require direct database access — communicates with the server via REST API.
+
+## Install
+
+```bash
+npm install -g @twin-build-orchestrate/cli
+```
+
+## Usage
+
+```bash
+# One-time config
+cat > .twin-build.json <<EOF
+{
+  "orchestrator": {
+    "serverUrl": "https://your-server.example.com",
+    "projectId": "your-project-uuid"
+  }
+}
+EOF
+export TWIN_BUILD_API_KEY="..."
+
+# Run as a foreground process
+twin-build-orchestrate start
+
+# Run detached (daemon)
+twin-build-orchestrate start --detach
+twin-build-orchestrate status
+twin-build-orchestrate stop
+```
+
+## Configuration
+
+| Source | Field |
+|--------|-------|
+| `.twin-build.json` `orchestrator.serverUrl` / env `TWIN_BUILD_SERVER_URL` | MCP server base URL |
+| `.twin-build.json` `orchestrator.projectId` / env `TWIN_BUILD_PROJECT_ID` | Project UUID to scope dispatch to |
+| env `TWIN_BUILD_API_KEY` (required) | API key for authentication |
+
+## Compatibility
+
+This client communicates with the twin-build MCP server REST API at `/api/v1/orchestrator/*`. Server version `>= 0.5.x` required.
+
+### Version matrix
+
+| `@twin-build-orchestrate/cli` | Required `twin-build-server` | Notes |
+|---|---|---|
+| `0.1.0` | `>= 0.5.0` | initial release |
+| `0.1.1` | **`>= 0.5.1`** | adds `POST /halt-task` endpoint for persistent worker setup failures (forsight #215). On older servers, the dispatcher leaves halted tasks in `in-progress` state and logs a warning — `agent_halt` events are still emitted so operators are notified. **Co-deploy server 0.5.1+ before upgrading the client.** |
+| `0.1.2` | `>= 0.5.1` (unchanged) | **client-only fix, no server upgrade required.** `linkClaudeAssets` now skips symlinking when the worktree's `.claude/<asset>` is a tracked-clean directory — projects that commit `.claude/rules/*` to git for team sharing (instead of the gitignored-symlink convention) no longer hit a persistent halt requiring manual `rm -rf` per ticket. Additional fixes: (1) git inspection failures (locked index, concurrent operations) classify as **transient** so the dispatcher requeues instead of halting; (2) macOS HFS+/APFS case-mismatch (`.claude/Rules/` vs `.claude/rules/`) is detected and rejected with a clear rename instruction; (3) `agent_halt.recommendedAction` now embeds the explicit 3-step recovery recipe. |
+
+## License
+
+MIT