@nickysagan/issue-orchestrator 0.1.3 → 0.2.0

package/README.md

@@ -76,6 +76,11 @@ 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.
 - **Complete** — Phase 6 marks the implementation PR ready for the owner. The
@@ -89,8 +94,14 @@ tmux attach -t orchestrator   # watch the workers directly
   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 is live.
+  window and no legacy window (below) is live.
 
 Live container pause/unpause check:
 [docs/smoke-checks/README.md](docs/smoke-checks/README.md).
@@ -107,6 +118,9 @@ 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.
 
+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.
+
 ## GitHub authentication
 
 `gh` does not auto-consume the GitHub App credential, so the supervisor mints a
@@ -133,7 +147,7 @@ Labels are created at startup — see the managed review gate above.
 | 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 (`address-review`, `github-issue`, `review-pr`, `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 |
 
@@ -144,6 +158,12 @@ Labels are created at startup — see the managed review gate above.
   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.
 
 The standalone `review-pr` and `address-review` skills remain installed for
 manual use, but the production supervisor route does not invoke them.

package/bin/supervisor.mjs

@@ -6,6 +6,7 @@ import { access, realpath } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import { promisify } from "node:util";
 import { createManagedContainerClient, resolveContainerId as resolveOwnContainerId } from "../src/managedContainer.mjs";
+import { describeEnforcementTransition } from "../src/enforcementNotice.mjs";
 import { BLOCKED, MERGE_REVIEW, READY, REVIEW, RUNNING, phaseOf } from "../src/labels.mjs";
 import { ensureLabels } from "../src/labels.mjs";
 import { selectApplicableMarker } from "../src/reviewMarker.mjs";
@@ -51,6 +52,38 @@ export async function isAgentSetupReady({ accessImpl = access } = {}) {
   }
 }
 
+// Admission control for new launches. The pinned `github-issue` skill refuses
+// to isolate issue work when the primary worktree is dirty, so claiming an
+// issue in that state only produces a worker that exits before opening a PR.
+// This runs the same predicate that guard runs — `git status --porcelain` —
+// before anything is claimed.
+//
+// The primary worktree is resolved explicitly rather than assumed to be the
+// caller's cwd: `git worktree list --porcelain` always reports it first, so a
+// supervisor started from inside a linked worktree still inspects the tree
+// isolation will actually branch from.
+//
+// Read-only by construction: it never stashes, resets, cleans, checks out, or
+// commits, and it fails closed — an unreadable result is not a clean one.
+export async function checkPrimaryWorktree({ exec }) {
+  try {
+    const { stdout: worktrees } = await exec("git", ["worktree", "list", "--porcelain"]);
+    const primary = String(worktrees).split("\n")
+      .find((line) => line.startsWith("worktree "))?.slice("worktree ".length).trim();
+    if (!primary) throw new Error("could not resolve the primary worktree");
+    const { stdout: status } = await exec("git", ["-C", primary, "status", "--porcelain"]);
+    const pending = String(status).split("\n").filter((line) => line.trim() !== "");
+    if (pending.length === 0) return { clean: true, reason: "clean", detail: "" };
+    return {
+      clean: false,
+      reason: "dirty",
+      detail: `${pending.length} pending change${pending.length === 1 ? "" : "s"} in ${primary}`,
+    };
+  } catch (err) {
+    return { clean: false, reason: "unreadable", detail: err.message };
+  }
+}
+
 export async function acquireSupervisorOwnership(repo, {
   createServer = createNetServer,
 } = {}) {
@@ -187,8 +220,8 @@ export function createGitHub({ exec, repo }) {
 
   const claim = (n) => setIssueLabels(n, { add: [RUNNING], remove: [READY] });
   // A launch that fails before any work exists reverts to the queue. This is
-  // the only path that removes `agent-running`, which is otherwise durable
-  // until Phase 7 cleanup.
+  // the only path that returns the issue to `agent-ready`; every other removal
+  // of `agent-running` goes through `release` below.
   const restore = (n) => setIssueLabels(n, { add: [READY], remove: [RUNNING] });
   // Implementation-only completion releases the active claim after the PR is
   // ready for the repository owner. The label itself remains the queue's
@@ -363,14 +396,19 @@ export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
 }
 
 // Map open PRs to the implementation issue they close. GitHub's parsed closing
-// linkage is authoritative; the conventional branch prefix is a fallback.
+// linkage is authoritative whenever the PR declares any, so a PR on
+// `agent/<other>-*` that closes a different issue never maps to the branch
+// number. The conventional branch prefix applies only to PRs that declare no
+// closing reference at all. Two or more applicable PRs are reported as
+// ambiguous rather than resolved to the first match: the caller must not act.
 export function implementationPrForIssue(prs, number) {
   const prefix = `agent/${number}-`;
-  const closesIssue = (pr) => Array.isArray(pr.closingIssuesReferences)
-    && pr.closingIssuesReferences.some((ref) => ref?.number === number);
-  const matchesBranch = (pr) => typeof pr.headRefName === "string"
-    && pr.headRefName.startsWith(prefix);
-  return (prs || []).find((pr) => closesIssue(pr) || matchesBranch(pr)) || null;
+  const applies = (pr) => (Array.isArray(pr.closingIssuesReferences) && pr.closingIssuesReferences.length > 0
+    ? pr.closingIssuesReferences.some((ref) => ref?.number === number)
+    : typeof pr.headRefName === "string" && pr.headRefName.startsWith(prefix));
+  const matches = (prs || []).filter(applies);
+  if (matches.length > 1) return { pr: null, ambiguous: true };
+  return { pr: matches[0] || null, ambiguous: false };
 }
 
 // Production poll route after the managed-review rollback. It deliberately
@@ -379,6 +417,7 @@ export function implementationPrForIssue(prs, number) {
 export async function runImplementationOnlyOnce({
   gh, tmux,
   checkSetupReady = async () => true,
+  checkPrimaryClean = async () => ({ clean: true, reason: "clean", detail: "" }),
   implementationSlots = IMPLEMENTATION_SLOTS,
   log,
   logs = NO_WORKER_LOGS,
@@ -386,13 +425,50 @@ export async function runImplementationOnlyOnce({
 }) {
   await tmux.ensureSession();
   const running = runningIssues !== undefined ? runningIssues : await gh.listRunningIssues();
+  // A supervisor restarted into an `orchestrator` session left by the managed
+  // review release inherits live `review-N`/`repair-N` windows this route never
+  // opens. They are read before any mutation, alongside the implementation
+  // windows, so an inspection failure aborts the poll rather than running with
+  // unknown capacity.
   const liveIssues = await tmux.listWorkerIssues();
+  const liveReview = await tmux.listReviewIssues();
+  const liveRepair = await tmux.listRepairIssues();
   const prs = await gh.listOpenPrs();
-  let liveCount = liveIssues.size;
+  // A legacy repair worker is a full `ccode` run sharing the implementation
+  // slots, exactly as it did before the rollback; a legacy reviewer had its own
+  // reserved slot and still consumes none.
+  let liveCount = liveIssues.size + liveRepair.size;
+
+  // Legacy windows are drained, never killed and never re-created: each may
+  // hold a worktree, a pushed branch, a draft PR and labels mid-transition, and
+  // the logic that knew how to finish or unwind that was removed with the
+  // managed review route. They exit on their own; until then they are visible
+  // here so nothing is launched over them and the supervisor cannot call itself
+  // idle. This line is the operator's only notice, so it names each one.
+  const legacyWindows = [
+    ...[...liveReview].sort((a, b) => a - b).map((n) => `review-${n}`),
+    ...[...liveRepair].sort((a, b) => a - b).map((n) => `repair-${n}`),
+  ];
+  if (legacyWindows.length > 0) {
+    log(`Legacy managed-review windows still live: ${legacyWindows.join(", ")}`
+      + " — draining; not managed, not restarted, and never killed by this supervisor");
+  }
 
   for (const issue of running) {
     try {
-      const pr = implementationPrForIssue(prs, issue.number);
+      // Releasing the claim, or acting on a PR a legacy worker is still
+      // editing, is the race this reconciliation exists to avoid. Defer the
+      // whole issue; once its legacy window exits, the next poll reconciles it
+      // by the ordinary rules.
+      if (liveReview.has(issue.number) || liveRepair.has(issue.number)) {
+        log(`#${issue.number} has a live legacy window — deferring reconciliation to a later poll`);
+        continue;
+      }
+      const { pr, ambiguous } = implementationPrForIssue(prs, issue.number);
+      if (ambiguous) {
+        log(`#${issue.number}: multiple open PRs claim this issue — leaving worker and claim untouched`);
+        continue;
+      }
       if (pr && pr.isDraft === false) {
         if (liveIssues.has(issue.number)) {
           await tmux.closeWorker(issue.number);
@@ -418,11 +494,30 @@ export async function runImplementationOnlyOnce({
   if (ready.length > 0 && !await checkSetupReady()) {
     log("Agent setup incomplete — pausing worker launches");
     return {
-      done: false, implLive: liveCount, reviewLive: 0,
+      done: false, implLive: liveCount, reviewLive: liveReview.size,
+      repairLive: liveRepair.size,
       started: 0, reviewsStarted: 0, repairsStarted: 0,
     };
   }
 
+  // Admission control. Isolation refuses a dirty primary worktree, so claiming
+  // an issue here would only burn a label transition on a worker that exits
+  // before opening a PR — which the next poll then misreports as vanished.
+  // Reconciliation above has already run, so live work keeps its slot, its
+  // claim and its lease; only new launches pause, and only for this poll.
+  if (ready.length > 0) {
+    const primary = await checkPrimaryClean();
+    if (!primary.clean) {
+      log(`Primary worktree ${primary.reason} (${primary.detail})`
+        + " — no issue claimed, worker launches paused this poll");
+      return {
+        done: false, implLive: liveCount, reviewLive: liveReview.size,
+        repairLive: liveRepair.size,
+        started: 0, reviewsStarted: 0, repairsStarted: 0,
+      };
+    }
+  }
+
   let started = 0;
   for (const number of ready) {
     if (liveCount >= implementationSlots) break;
@@ -448,9 +543,12 @@ export async function runImplementationOnlyOnce({
   }
 
   return {
-    done: ready.length === 0 && liveCount === 0,
+    // `done` drops the Sentinel lease and stops the supervisor, so a live
+    // legacy worker of either kind must hold it false.
+    done: ready.length === 0 && liveCount === 0 && liveReview.size === 0,
     implLive: liveCount,
-    reviewLive: 0,
+    reviewLive: liveReview.size,
+    repairLive: liveRepair.size,
     started,
     reviewsStarted: 0,
     repairsStarted: 0,
@@ -853,13 +951,48 @@ export async function main({
   createLeaseClient = createConfiguredLease,
   runPoll = runImplementationOnlyOnce,
   checkSetupReady = isAgentSetupReady,
+  checkPrimaryClean = () => checkPrimaryWorktree({ exec }),
   sleepImpl = sleep,
   log = (message) => console.log(formatLogLine(message)),
+  stdout = process.stdout,
 } = {}) {
   const repo = await resolve(exec);
   const releaseOwnership = await acquireOwnership(repo);
   const lease = createLeaseClient();
   let containerId;
+  // Docker freezes this process rather than restarting it, so the last observed
+  // enforcement state survives the pause in memory — nothing needs persisting.
+  let enforcementState = "running";
+
+  // Resolves only once the line has actually left the process. Workers run under
+  // `tmux … | tee`, where stdout is a pipe and `console.log` does not block, so
+  // an unflushed pause message could lose the race against Docker.
+  function logFlush(message) {
+    return new Promise((resolve, reject) => {
+      stdout.write(`${formatLogLine(message)}\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  // Announce a transition, flush it, then acknowledge — in that order. The
+  // acknowledgment lets Sentinel pause this very container, so an unflushed
+  // message would race Docker and could be lost. A failed acknowledgment is
+  // visible but not fatal: Sentinel pauses anyway once its timeout elapses, so
+  // failing here would cost availability without adding enforcement.
+  //
+  // The parameter default covers a client that predates the enforcement field;
+  // the current one always parses and returns it.
+  async function notifyEnforcement(enforcement = { state: "running" }) {
+    const transition = describeEnforcementTransition(enforcementState, enforcement);
+    enforcementState = transition.state;
+    if (transition.message) await logFlush(transition.message);
+    if (!transition.acknowledge) return;
+    try {
+      await lease.acknowledge(containerId);
+    } catch (err) {
+      log(`pause acknowledgment failed: ${err.message}`);
+    }
+  }
+
   try {
     // One helper for the whole run: the launcher that reserves an attempt and
     // the poll that later reads it must agree on where the logs live.
@@ -889,8 +1022,9 @@ export async function main({
     // silently running unenforced.
     try {
       containerId = await resolveContainer();
-      const { status } = await lease.register(containerId);
+      const { status, enforcement } = await lease.register(containerId);
       log(`Managed container lease ${status} for ${containerId}`);
+      await notifyEnforcement(enforcement);
     } catch (err) {
       throw new Error(`managed-container registration failed: ${err.message}`);
     }
@@ -902,7 +1036,8 @@ export async function main({
     for (let firstPoll = true; ; firstPoll = false) {
       if (!firstPoll) {
         try {
-          await lease.register(containerId);
+          const { enforcement } = await lease.register(containerId);
+          await notifyEnforcement(enforcement);
         } catch (err) {
           log(`lease heartbeat failed: ${err.message}`);
         }
@@ -912,7 +1047,7 @@ export async function main({
         const token = await mint(repo);
         const gh = createGitHub({ exec: authExec(token), repo });
         result = await runPoll({
-          gh, tmux, checkSetupReady,
+          gh, tmux, checkSetupReady, checkPrimaryClean,
           implementationSlots: IMPLEMENTATION_SLOTS,
           reviewerSlots: REVIEWER_SLOTS,
           log, logs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickysagan/issue-orchestrator",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "A small, supervised GitHub issue queue that keeps autonomous coding workers alive.",
   "license": "MIT",
   "repository": {

package/src/enforcementNotice.mjs

@@ -0,0 +1,36 @@
+// Sentinel's enforcement state is a lease field, not an admission decision.
+// This module only decides what to say about a change in it, and whether the
+// change still needs acknowledging; it reads no usage and gates nothing.
+const WINDOW_NAMES = { short: "5-hour", long: "weekly" };
+
+function pauseMessage(reason) {
+  const window = WINDOW_NAMES[reason.window];
+  const short = Math.round(reason.shortUsedPercent);
+  const long = Math.round(reason.longUsedPercent);
+  const resets = reason.resetsAt === null ? "" : ` Usage resets at ${reason.resetsAt}.`;
+  return (
+    `Sentinel usage threshold reached on the ${window} window ` +
+    `(5-hour ${short}%, weekly ${long}%); pausing this container until usage ` +
+    `becomes available.${resets}`
+  );
+}
+
+export function describeEnforcementTransition(previousState, enforcement) {
+  const state = enforcement.state;
+  // Acknowledgment is independent of the message: a pause announced on one
+  // heartbeat whose acknowledgment failed is retried on the next one without
+  // printing a second line.
+  const acknowledge = state === "pause_pending" && enforcement.acknowledged !== true;
+  if (state === previousState) return { state, message: null, acknowledge };
+  if (state === "running") {
+    return { state, message: "Sentinel unpaused this container; issue-orchestrator resumed.", acknowledge };
+  }
+  if (previousState === "running") {
+    // Announcing on any first departure from `running` covers a lease seen as
+    // `paused` outright — a Sentinel restart, or a pause whose persist raced —
+    // which would otherwise freeze the container in silence.
+    return { state, message: pauseMessage(enforcement.reason), acknowledge };
+  }
+  // pause_pending → paused: the same pause, already announced.
+  return { state, message: null, acknowledge };
+}

package/src/managedContainer.mjs

@@ -19,6 +19,41 @@ export async function resolveContainerId({ readFileImpl = readFile } = {}) {
   throw new Error(`ambiguous Docker container IDs in /proc/self/mountinfo: ${[...ids].join(", ")}`);
 }
 
+const WINDOWS = new Set(["short", "long"]);
+
+function isPercent(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 100;
+}
+
+function isReason(value) {
+  return (
+    typeof value === "object" && value !== null &&
+    WINDOWS.has(value.window) &&
+    isPercent(value.shortUsedPercent) &&
+    isPercent(value.longUsedPercent) &&
+    (value.resetsAt === null || typeof value.resetsAt === "string")
+  );
+}
+
+// Sentinel documents an absent field as `running`, so only a *present* payload
+// can be malformed. A malformed one throws: this client never invents a state,
+// because a wrong guess would either hide an imminent pause or announce one
+// that is not coming.
+function parseEnforcement(value) {
+  if (value === undefined || value === null) return { state: "running" };
+  if (typeof value !== "object") {
+    throw new Error("invalid managed-container enforcement: not an object");
+  }
+  if (value.state === "running") return { state: "running" };
+  if (value.state !== "pause_pending" && value.state !== "paused") {
+    throw new Error(`invalid managed-container enforcement: unknown state ${value.state}`);
+  }
+  if (!isReason(value.reason)) {
+    throw new Error("invalid managed-container enforcement: invalid reason");
+  }
+  return value;
+}
+
 // Sentinel's `/managed-containers` API is a lease, not admission control: it
 // never allows or denies a start, so neither operation here returns anything a
 // caller could read as a decision. Any non-lease status is a local or transport
@@ -61,12 +96,12 @@ export function createManagedContainerClient({
     return new Error(`${prefix}: ${detail}`);
   }
 
-  async function request(containerId, method) {
+  async function request(containerId, method, suffix = "") {
     if (typeof containerId !== "string" || !CONTAINER_ID.test(containerId)) {
       throw new Error(`invalid container ID: ${containerId}`);
     }
     const { signal, done } = startDeadline();
-    const path = `/managed-containers/${encodeURIComponent(containerId)}`;
+    const path = `/managed-containers/${encodeURIComponent(containerId)}${suffix}`;
     let response;
     try {
       response = await withDeadline(fetchImpl(`${baseUrl}${path}`, { method, signal }), signal);
@@ -102,12 +137,24 @@ export function createManagedContainerClient({
       if (body?.status !== expected) {
         throw new Error(`invalid managed-container registration response: status ${body?.status}`);
       }
-      return { status: expected };
+      return { status: expected, enforcement: parseEnforcement(body.enforcement) };
     } finally {
       done();
     }
   }
 
+  // Tells Sentinel the pre-pause message has been printed, so it may pause this
+  // container. `409 no pending pause` is not a failure: it only means Sentinel
+  // already resolved the transition — its acknowledgment timeout fired, or usage
+  // dropped back below the threshold.
+  async function acknowledge(containerId) {
+    const { response, done } = await request(containerId, "POST", "/acknowledge");
+    done();
+    if (response.status === 200) return { acknowledged: true };
+    if (response.status === 409) return { acknowledged: false };
+    throw new Error(`unexpected managed-container acknowledgment status ${response.status}`);
+  }
+
   async function unregister(containerId) {
     const { response, done } = await request(containerId, "DELETE");
     done();
@@ -116,5 +163,5 @@ export function createManagedContainerClient({
     }
   }
 
-  return { register, unregister };
+  return { register, unregister, acknowledge };
 }

package/src/reviewGate.mjs

@@ -188,7 +188,8 @@ export function planLabelMirror(issueLabels, prLabels) {
 }
 
 // Swap the issue's phase label and mirror it onto the PR. `agent-running` is
-// never removed here — it is durable until Phase 7.
+// never removed here — it survives every phase swap, and only the supervisor
+// releases it, once the PR is ready for the owner.
 export async function setPhase({ gh, issue, pr, phase }) {
   const deltaFor = (labels) => {
     const current = new Set(labels || []);