npm - @nickysagan/issue-orchestrator - Versions diffs - 0.1.2 → 0.2.0 - Mend

@nickysagan/issue-orchestrator 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/README.md +99 -215
package/bin/supervisor.mjs +497 -29
package/package.json +1 -1
package/src/enforcementNotice.mjs +36 -0
package/src/managedContainer.mjs +51 -4
package/src/repairGate.mjs +57 -0
package/src/repairMarker.mjs +248 -0
package/src/reviewGate.mjs +18 -8
package/src/workerLogs.mjs +14 -10

package/README.md CHANGED Viewed

@@ -6,18 +6,21 @@ subscription-authenticated `ccode` implementation workers alive — each in its
 tmux window running:
 ```bash
-ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue <number>"
+ccode --print --permission-mode auto --model claude-opus-5 "/github-issue <number>"
 ```
+The full model name pins implementation workers to Opus 5 rather than the
+Claude Code default or the moving `opus` alias. Non-interactive print mode
+skips the workspace-trust prompt, and each process exits — closing its tmux
+window — once its command finishes.
 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.
+than this repository stopping workers itself.
-A finished PR is not merged automatically. It first passes through the managed
-review gate below, which uses a third, separately reserved worker slot.
+A finished implementation PR is marked ready for the repository owner. The
+supervisor does not review, repair, approve, or merge it automatically.
 ## Orchestrator
@@ -44,37 +47,24 @@ 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>"
-```
+also exposes that command through the literal alias `start work`.
-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.
+The supervisor resolves the `origin` of that working directory, checks GitHub App
+authentication, registers its own container with Sentinel, and starts the
+autonomous workers itself. Do not start Claude separately. A supervisor that
+cannot resolve its container ID or register its lease exits nonzero rather than
+run unenforced.
 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.
+time; a second invocation for the same resolved `owner/repo` exits nonzero with
+`already running` before authentication, the lease, tmux, or worker startup.
+Ownership is a kernel-owned Linux abstract Unix socket, released on normal exit
+and automatically when the process dies. Devcontainers normally have distinct
+network namespaces and therefore independent guards; containers sharing a
+namespace share this guard.
+Neither the image build nor devcontainer startup launches the supervisor or an
+LLM. Work begins only when a user runs `issue-orchestrator` or `start work`.
 ### Repository-checkout usage
@@ -86,227 +76,121 @@ tmux attach -t orchestrator   # watch the workers directly
 ### How it works
+- **Admission** — before anything is claimed, the primary worktree is checked
+  with a read-only `git status --porcelain`. If it has pending changes — or if
+  that check cannot be read — no issue is claimed and no worker starts for that
+  poll; nothing is stashed, reset, cleaned, or committed. Live workers keep
+  running and are reconciled as usual.
 - **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. A
-  run that reaches its end stamps a final `[orchestrator <ISO>] ... finished ...`
-  line into its log, so a tail can be placed in time without the file's mtime.
-- **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.
+  `agent-ready` → `agent-running`, then a tmux window `issue-<n>` opens.
+- **Complete** — Phase 6 marks the implementation PR ready for the owner. The
+  next poll closes any remaining worker window, removes `agent-running` from
+  the issue, and frees the slot.
+- **Vanished** — if a worker disappears while its PR is still draft or absent,
+  the claim is released and the draft/worktree is preserved. It is not
+  restarted automatically.
+- **Worker logs** — every implementation launch writes combined output to
+  `<git-common-dir>/issue-orchestrator/logs/issue-<n>.<attempt>.log`, keeping
+  the latest three attempts and scrubbing secrets from surfaced tails.
+- **Usage enforcement** — Usage Sentinel owns pause/unpause thresholds. This
+  repository reads no usage telemetry and never kills a worker for usage.
+- **Pause notices** — the managed-container heartbeat carries Sentinel's
+  enforcement state. A pending pause prints one flushed line naming the
+  triggering window, both observed percentages and the reset time, and is then
+  acknowledged so Sentinel may pause; the first heartbeat back to `running`
+  prints one resume line. Ordinary refreshes stay quiet, and a payload that is
+  present but malformed is reported rather than guessed at.
+- **Stop** — the supervisor exits when nothing is queued and no implementation
+  window and no legacy window (below) is live.
 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).
+## Implementation-only handoff
-| 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` remains the active ownership marker: it is applied when an
+issue is claimed and removed only after the implementation PR is ready for the
+owner, or when a vanished/failed launch is safely released. Existing review
+labels are left untouched in repositories, but the supervisor does not create a
+reviewer or repair worker and does not transition issues through them.
-`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.
+Manual and managed `/github-issue` runs both finish by marking the PR ready.
+Human review and merge begin there. The supervisor exposes no approve or merge
+operation.
-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"} -->
-```
+Legacy `review-<n>` and `repair-<n>` windows are allowed to finish without being
+restarted or killed; both keep the supervisor active, and repairs consume an implementation slot.
-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
+## 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
+short-lived 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.
+re-minting each poll. At startup an authenticated `gh repo view` smoke check
+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:
+The local concurrency guard is fixed at two implementation slots. 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.
+Labels are created at startup — see the managed review gate above.
 ## 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 |
+| `.agents/skills/` | Installed skills (`address-review`, `github-issue`, `github-pr-cleanup`, `review-pr`, `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.
+- **`github-issue`** — runs an issue end to end, opens a draft PR, implements
+  in an isolated worktree, verifies the result, and marks the PR ready for the
+  owner.
 - **`setup`** — connects the repo to the `container-coding-agent` GitHub App
   and verifies `git`/`gh` authenticate as the App.
+- **`github-pr-cleanup`** — cleans the worktree, branch and session artifacts of
+  one merged or closed pull request. Worktree Warden is the automatic caller: it
+  watches for terminal pull requests and runs the skill's cleanup script, so
+  cleanup happens outside this repository's supervisor, which ends at "PR ready
+  for the owner". The skill is installed here so that script exists in a
+  checkout, and so it can also be run by hand for a single pull request.
-Both are sourced from [`Sadotu/agent-skills`](https://github.com/Sadotu/agent-skills).
+The standalone `review-pr` and `address-review` skills remain installed for
+manual use, but the production supervisor route does not invoke them.
 ## Releasing
-`package.json` holds the version, and merging the bump is the whole release.
-Bump it in a normal pull request; when that lands on `main`,
-`.github/workflows/publish.yml` sees a version the registry does not carry,
-runs the tests, publishes, and pushes the matching `v<version>` tag. A merge
-that does not bump the version finds its version already published and exits
-without releasing anything.
+`package.json` holds the version, and merging the bump is the whole release. Bump
+it in a normal pull request; when that lands on `main`,
+`.github/workflows/publish.yml` sees a version the registry does not carry, runs
+the tests, publishes, and pushes the matching `v<version>` tag. A merge without a
+bump finds its version already published and exits without releasing. Pushing a
+`v*` tag by hand takes the same path, with one extra guard: the tag must equal
+`v<version>` or the run fails. A published version cannot be republished; bump
+and merge again.
 Publishing goes 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. Tagging is a second job, so the job holding an npm
-credential cannot write to this repository and the job that can push a tag
-holds no npm credential. A published version cannot be republished; bump and
-merge again.
-Pushing a `v*` tag by hand still works and takes the same path, with one extra
-guard: the tag must equal `v<version>` or the run fails.
-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**.
+[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. Tagging is a separate job, so the job holding an npm credential
+cannot write to this repository and the job that can push a tag holds no npm
+credential.
+Two one-time bootstraps, both because they need a package that already exists:
+`0.1.0` was published by hand (`npm login && npm publish`) to enable trusted
+publishing, and package visibility — set on the package, not inherited from this
+private repository — must be set once after the first release under **Sadotu →
+Packages → issue-orchestrator → Package settings**.
 ## Development environment