@nickysagan/issue-orchestrator 0.1.0

package/README.md

@@ -0,0 +1,314 @@
+# issue-orchestrator
+
+A small, supervised issue queue. A single Node supervisor picks up open issues
+labeled `agent-ready` (ascending) and keeps at most **two** autonomous
+subscription-authenticated `ccode` implementation workers alive — each in its own
+tmux window running:
+
+```bash
+ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <number>"
+```
+
+Usage limits are enforced by
+[Usage Sentinel](https://github.com/Sadotu/usage-sentinel), which pauses this
+orchestrator's entire Docker container — supervisor and workers together — rather
+than this repository stopping workers itself. The full model name pins issue
+workers to Opus 4.8 instead of the Claude Code default or the moving `opus`
+alias.
+
+A finished PR is not merged automatically. It first passes through the managed
+review gate below, which uses a third, separately reserved worker slot.
+
+## Orchestrator
+
+Zero-dependency Node ≥20.8.0 on Linux (the supervisor guard uses a Linux abstract
+Unix socket). No build step.
+
+### Installed/current-repository usage
+
+The package is published publicly on
+[npmjs](https://www.npmjs.com/package/@nickysagan/issue-orchestrator), so no
+registry configuration or token is needed:
+
+```bash
+npm install -g @nickysagan/issue-orchestrator@latest
+```
+
+The scope names the package; the installed command is `issue-orchestrator`.
+
+Run it from the target project repository, not from the package checkout:
+
+```bash
+cd /path/to/target-project
+issue-orchestrator
+```
+
+The shared [`agent-devcontainer`](https://github.com/Sadotu/agent-devcontainer)
+also exposes that command through the literal alias:
+
+```bash
+start work
+```
+
+The supervisor resolves the `origin` of that current working directory,
+checks GitHub App authentication, registers its own container with Sentinel, and
+starts autonomous workers itself:
+
+```bash
+ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <number>"
+```
+
+Non-interactive print mode skips the workspace-trust prompt, and each process
+exits after its command finishes. A supervisor that cannot resolve its container
+ID or register its lease exits nonzero rather than run unenforced. Do not start
+Claude separately.
+
+Only one supervisor per repository per Linux network namespace may run at a
+time. A second invocation in the same namespace for the same resolved
+`owner/repo` exits nonzero with an `already running` error before
+authentication, the container lease, tmux, or worker startup. Ownership is held by a
+kernel-owned Linux abstract Unix socket, so it is released on normal exit and
+automatically when the supervisor process dies. Devcontainers normally have
+distinct network namespaces and therefore independent guards; containers that
+share a network namespace also share this guard.
+
+Neither the image build nor devcontainer startup launches the supervisor or
+an LLM. Work begins only when a user explicitly runs `issue-orchestrator` or
+its `start work` alias.
+
+### Repository-checkout usage
+
+```bash
+npm test                 # node --test over test/
+node bin/supervisor.mjs  # start the supervisor loop
+tmux attach -t orchestrator   # watch the workers directly
+```
+
+### How it works
+
+- **Claim** — the lowest-numbered `agent-ready` issue has its label swapped
+  `agent-ready` → `agent-running`, then a tmux window `issue-<n>` opens running
+  this autonomous command:
+
+  ```bash
+  ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <n>"
+  ```
+
+  Non-interactive print mode skips the workspace-trust prompt; the process exits
+  and its tmux window closes after the command finishes.
+- **Complete** — a worker finishes by leaving its PR in draft and putting
+  `agent-review` on the issue. Reaching any phase label is what marks
+  implementation done: the supervisor closes the tmux window and frees the slot,
+  and `agent-running` stays. An already-closed window is treated as closed; a
+  failure at any later step is logged and retried by the next poll.
+- **Vanished** — if a worker window disappears before the issue reaches a phase
+  label, the workflow died. There is no repair worker, so the supervisor fails
+  closed: it comments on the issue — including the vanished worker's log path
+  and the tail of its output — and sets `agent-blocked`. The issue is never
+  restarted automatically, because its draft PR or worktree may still exist.
+- **Worker logs** — every launch `tee`s the window's combined output to
+  `<git-common-dir>/issue-orchestrator/logs/<issue|review>-<n>.<attempt>.log`,
+  keeping the latest three attempts. Surfaced tails are scrubbed of secrets.
+- **Active-container lease** — at startup the supervisor resolves its own exact
+  64-character Docker container ID (from `/proc/self/mountinfo`; the short
+  `hostname` form is not accepted) and registers it with
+  `PUT /managed-containers/<id>` on Sentinel. Registration is a lease, not an
+  admission decision: Sentinel never allows or denies a start. Every later poll
+  re-PUTs the same ID as its heartbeat, well inside the five-minute lease; a
+  clean exit `DELETE`s it as best-effort cleanup, and an abrupt exit is handled
+  by Sentinel's lease expiry. A failed heartbeat is logged and retried on the
+  next poll. The supervisor keeps a local guard of two implementation workers
+  plus one reviewer.
+- **Usage enforcement lives in Sentinel** — when Claude Code's five-hour or
+  weekly window reaches 95%, Sentinel `docker pause`s every registered container,
+  freezing this supervisor and every worker process in place, and unpauses only
+  after a fresh valid reading puts both windows below 95%. This repository reads
+  no usage telemetry, applies no thresholds, calls no Docker API, and never kills
+  a worker because of usage.
+- **Stop** — the supervisor exits when nothing is queued, no worker or reviewer
+  window is live, and every managed issue rests in `agent-blocked` or
+  `user-merge-review`. Merge and post-merge cleanup monitoring are not yet
+  implemented.
+
+Live container pause/unpause check:
+[docs/smoke-checks/README.md](docs/smoke-checks/README.md).
+
+## Managed review gate
+
+A managed PR receives an independent automated review and then either stops with
+documented blockers or becomes ready for the owner. The supervisor never
+approves and never merges.
+
+### Labels
+
+At startup — after the repository is resolved and the GitHub App auth check
+passes, and before the first poll — the supervisor creates any of these labels
+that the repository is missing. Labels that already exist are never renamed,
+recoloured, or re-described, and no GitHub mutation ever happens at image-build
+time (the build has neither a target repository nor runtime credentials).
+
+| Label | Colour | Meaning |
+|---|---|---|
+| `agent-ready` | `0e8a16` | Ready for issue-orchestrator claim |
+| `agent-running` | `1d76db` | Managed by issue-orchestrator |
+| `agent-review` | `5319e7` | Waiting for or undergoing automated review |
+| `agent-blocked` | `d73a4a` | Automated workflow blocked; findings posted |
+| `user-merge-review` | `fbca04` | Automated review passed; waiting for owner review and merge |
+
+`agent-running` is the durable ownership marker: it is applied at claim and
+stays until post-merge cleanup (not yet implemented). Exactly one phase label —
+`agent-review`, `agent-blocked`, or `user-merge-review` — is active alongside
+it. Issue labels are canonical and the PR mirrors them; every poll repairs a
+mismatch, issuing an edit only when the sets actually differ.
+
+A PR with no linked `agent-running` issue is ignored entirely — manual
+`/github-issue` PRs and unrelated `agent/*` branches are never touched. More
+than one PR closing an issue, a branch that disagrees with its closing
+reference, or an `agent-review` issue with no PR all fail closed: an actionable
+comment plus `agent-blocked`.
+
+### Capacity
+
+Two reserved implementation slots plus one reviewer slot that is never borrowed
+for implementation. The pools are separate tmux window namespaces — `issue-<n>`
+and `review-<n>` — each counting only its own live windows. The oldest eligible
+`agent-review` PR gets a fresh reviewer window running:
+
+```bash
+ccode --print --permission-mode auto --model claude-opus-4-8 "/review-pr <pr>"
+```
+
+The reviewer slot frees as soon as that window exits. Waiting on CI holds no
+slot, because it is pure label state with no window.
+
+### Review marker
+
+The reviewer (`Sadotu/agent-skills`, `review-pr`) records each pass in one
+immutable PR comment carrying a single-line marker:
+
+```
+<!-- review-pr:v1 {"fingerprint":"<64-hex>","head":"<40-hex>","base":"<40-hex>","issueUpdatedAt":"<ISO>","prUpdatedAt":"<ISO>","issue":41,"pr":72,"pass":1,"verdict":"PASS"} -->
+```
+
+The reviewer is the producer and owns this format; this repository only consumes
+it. Verdicts are exactly `PASS` and `BLOCKING`.
+
+A marker is applied only when all three hold:
+
+- **Authorship** — the comment has `viewerDidAuthor: true`, so the same GitHub
+  App identity the supervisor authenticates as wrote it. Every fingerprint input
+  is public, so without this check any commenter could forge a `PASS`.
+- **Identity** — its `issue` and `pr` are the managed pair being gated.
+- **Freshness** — its `fingerprint` equals the live fingerprint,
+  `sha256(head 0x1e base 0x1e issue-body 0x1e pr-body)`. Bodies decide
+  freshness, not `updatedAt`: a new comment or a label edit moves the timestamps
+  while reviewing the same content, whereas any real change to the head, the
+  base, the issue text, or the PR text invalidates the pass. `issueUpdatedAt`
+  and `prUpdatedAt` are recorded for audit only.
+
+Comparing against live state rather than a snapshot captured at launch needs no
+persistence, so the same content is handled once even across a supervisor
+restart or a crash between the comment and the label transition. A marker that
+fails any check is discarded silently: nothing is posted, nothing transitions,
+and the PR simply queues a fresh pass. Parsing fails closed on an unsupported
+tag, malformed JSON, or a missing or ill-typed field. A trusted, applicable
+marker carrying an unsupported *verdict* is the one case that is not discarded —
+it blocks, so a contract break surfaces instead of looping.
+
+### Transitions
+
+**`BLOCKING`** — the PR is kept or returned to draft and `agent-review` becomes
+`agent-blocked` on issue and PR. The reviewer's findings stand alone in its own
+comment; the supervisor adds nothing and stops. There is no automatic repair.
+
+**`PASS`** — the PR is marked ready for review first, so repositories whose CI
+triggers on `ready_for_review` start their checks. Checks are read on the
+following poll, never in the same one that opened the PR:
+
+| Checks | Outcome |
+|---|---|
+| None configured | Green → `user-merge-review` |
+| All complete and successful, neutral, or skipped | Green → `user-merge-review` |
+| Any still running | Keep `agent-review`; reviewer slot stays free |
+| Any failed | Return to draft, `agent-blocked`, post the failing check names and URLs |
+| Data unreadable | Transition nothing; retry next poll |
+
+Every check GitHub reports is treated as required. "No checks configured" and
+"could not read the checks" are deliberately distinct: only the former counts as
+green.
+
+### GitHub authentication
+
+`gh` does not auto-consume the GitHub App credential, so the supervisor mints a
+short-lived App installation token (via `gh-app-token.sh`, overridable with
+`GH_APP_TOKEN_SCRIPT`) and injects it as `GH_TOKEN` for every `gh` call,
+re-minting each poll. At startup it runs an authenticated `gh repo view` smoke
+check and exits with a clear message if the App is not authenticated — rather
+than churning on unauthenticated calls every poll.
+
+### Configuration
+
+The local concurrency guard is fixed at two implementation slots plus one
+reviewer slot. Two knobs are environment-tunable:
+
+| Var | Default | Meaning |
+|-----|---------|---------|
+| `SENTINEL_URL` | `http://usage-sentinel:4317` | Usage Sentinel base URL for the managed-container lease, on the shared container network; set this explicitly (for example, `http://host.docker.internal:4317`) only when Sentinel is exposed on the host |
+| `POLL_MS` | `60000` | Poll interval |
+
+Labels are created at startup — see the managed review gate below.
+
+## Repo contents
+
+| Path | Purpose |
+|------|---------|
+| `agents.toml` / `agents.lock` | [dotagents](https://github.com/Sadotu/agent-skills) manifest — declares which skills are installed and pins their source commits |
+| `.agents/skills/` | Installed skills (`github-issue`, `setup`) — managed artifacts, restored from the manifest, not committed |
+| `.claude/skills` | Symlink to `.agents/skills` so Claude Code picks the skills up |
+| `CLAUDE.md` | Agent instructions and gotchas for working in this repo |
+
+## Skills
+
+- **`github-issue`** — runs a GitHub issue end to end: select issue, open a
+  draft PR immediately, self-resolve design decisions (logged to the PR),
+  implement in an isolated worktree, verify against the issue, mark ready.
+- **`setup`** — connects the repo to the `container-coding-agent` GitHub App
+  and verifies `git`/`gh` authenticate as the App.
+
+Both are sourced from [`Sadotu/agent-skills`](https://github.com/Sadotu/agent-skills).
+
+## Releasing
+
+`package.json` holds the version; the tag only confirms it. Bump it in a normal
+pull request, then tag the merge commit:
+
+```bash
+git tag v0.2.0 && git push origin v0.2.0
+```
+
+`.github/workflows/publish.yml` publishes to npmjs via
+[trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm
+token is stored anywhere: npm exchanges the workflow's OIDC identity for a
+short-lived credential. It refuses to publish unless the tag equals
+`v<version>` and the tests pass. A published version cannot be republished;
+bump and tag again.
+
+Trusted publishing can only be configured on a package that already exists, so
+`0.1.0` was published by hand (`npm login && npm publish`) to bootstrap it.
+Every later release goes through the workflow.
+
+Package visibility is set on the package, not inherited from this private
+repository, and the setting appears only once a version exists. So after the
+**first** release, set it once under **Sadotu → Packages →
+issue-orchestrator → Package settings**.
+
+## Development environment
+
+Agents work on this repo from a shared, sandboxed devcontainer. That
+environment is **not part of this app** — it lives in its own repo:
+[`Sadotu/agent-devcontainer`](https://github.com/Sadotu/agent-devcontainer)
+(image, setup scripts, security model, auth docs). A local `.devcontainer/`
+folder pointing at that image may exist in a checkout but is gitignored.
+
+GitHub access is via the scoped `container-coding-agent` GitHub App — never a
+personal token, never `gh auth login`. See `CLAUDE.md` for the auth wiring.