@nickysagan/issue-orchestrator 0.1.0

package/bin/supervisor.mjs

@@ -0,0 +1,614 @@
+#!/usr/bin/env node
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createServer as createNetServer } from "node:net";
+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 { BLOCKED, MERGE_REVIEW, READY, REVIEW, RUNNING, phaseOf } from "../src/labels.mjs";
+import { ensureLabels } from "../src/labels.mjs";
+import { selectApplicableMarker } from "../src/reviewMarker.mjs";
+import { createWorkerLogs } from "../src/workerLogs.mjs";
+import {
+  applyReviewPlan, classifyChecks, failClosed, mirrorLabels, planVerdict, resolveManagedPrs,
+} from "../src/reviewGate.mjs";
+
+const run = promisify(execFile);
+
+// ---- Configuration ----------------------------------------------------------
+// Fixed defaults per the issue's simplicity constraints. Only the Sentinel URL
+// and the poll interval are environment-tunable.
+//
+// Two reserved implementation slots plus one reviewer slot that is never
+// borrowed for implementation. The pools are separate counters over separate
+// tmux window namespaces, so an orphan in one role can never eat the other's.
+const IMPLEMENTATION_SLOTS = 2;
+const REVIEWER_SLOTS = 1;
+const POLL_MS = Number(process.env.POLL_MS || 60000);
+const TOKEN_SCRIPT = process.env.GH_APP_TOKEN_SCRIPT || "/opt/agent-devcontainer/gh-app-token.sh";
+const SESSION = "orchestrator";
+const AGENT_SETUP_MARKER = "/run/agent-devcontainer/agent-setup-complete";
+
+export async function isAgentSetupReady({ accessImpl = access } = {}) {
+  try {
+    await accessImpl(AGENT_SETUP_MARKER);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function acquireSupervisorOwnership(repo, {
+  createServer = createNetServer,
+} = {}) {
+  const key = createHash("sha256").update(repo).digest("hex");
+  // Linux abstract Unix sockets are kernel-owned: bind is atomic, creates no
+  // filesystem state, and is automatically released when the process dies.
+  // The installed CLI runs in the Linux agent-devcontainer targeted by this repo.
+  const address = `\0issue-orchestrator-${key}`;
+  const server = createServer((socket) => socket.destroy());
+
+  await new Promise((resolve, reject) => {
+    function onError(error) {
+      server.off("listening", onListening);
+      if (error.code === "EADDRINUSE") {
+        reject(new Error(`supervisor already running for ${repo}`));
+      } else {
+        reject(error);
+      }
+    }
+    function onListening() {
+      server.off("error", onError);
+      resolve();
+    }
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(address);
+  });
+
+  let releasePromise;
+  return async function release() {
+    if (!releasePromise) {
+      releasePromise = new Promise((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+      });
+    }
+    return releasePromise;
+  };
+}
+
+// Sentinel's managed-container lease: it records where an active orchestrator
+// runs so Sentinel can pause that container at the usage thresholds. It carries
+// no admission decision and never gates a start.
+export function createConfiguredLease({ env = process.env, fetchImpl = fetch } = {}) {
+  const url = env.SENTINEL_URL || "http://usage-sentinel:4317";
+  return createManagedContainerClient({ url, fetchImpl });
+}
+
+// ---- exec -------------------------------------------------------------------
+// Returns an `exec(file, args) => Promise<{stdout, stderr}>` bound to a fixed
+// environment. Injected into the adapters so tests never spawn real processes.
+export function makeExec(env = process.env) {
+  return async function exec(file, args) {
+    const { stdout, stderr } = await run(file, args, { env, maxBuffer: 10 * 1024 * 1024 });
+    return { stdout, stderr };
+  };
+}
+
+// ---- GitHub adapter ---------------------------------------------------------
+const PR_FIELDS = [
+  "number", "headRefName", "headRefOid", "baseRefOid", "body", "isDraft", "url",
+  "updatedAt", "createdAt", "labels", "closingIssuesReferences", "statusCheckRollup",
+].join(",");
+
+export function createGitHub({ exec, repo }) {
+  const R = ["--repo", repo];
+  const names = (labels) => (Array.isArray(labels) ? labels.map((l) => l.name) : []);
+
+  async function listReadyIssues() {
+    const { stdout } = await exec("gh", [
+      "issue", "list", ...R, "--label", READY, "--state", "open",
+      "--json", "number", "--limit", "100",
+    ]);
+    return JSON.parse(stdout || "[]").map((i) => i.number).sort((a, b) => a - b);
+  }
+
+  // Labels come back with the issue so phase state costs no extra call; the
+  // body rides along too, because it is a review-marker fingerprint input.
+  async function listRunningIssues() {
+    const { stdout } = await exec("gh", [
+      "issue", "list", ...R, "--label", RUNNING, "--state", "open",
+      "--json", "number,labels,updatedAt,body", "--limit", "100",
+    ]);
+    return JSON.parse(stdout || "[]")
+      .map((i) => ({ number: i.number, labels: names(i.labels), updatedAt: i.updatedAt, body: i.body }))
+      .sort((a, b) => a.number - b.number);
+  }
+
+  // One call per poll carries everything the review gate needs: the marker
+  // fingerprint inputs (SHAs and body), mirror labels, and the check rollup.
+  async function listOpenPrs() {
+    const { stdout } = await exec("gh", [
+      "pr", "list", ...R, "--state", "open", "--json", PR_FIELDS, "--limit", "100",
+    ]);
+    return JSON.parse(stdout || "[]").map((pr) => ({ ...pr, labels: names(pr.labels) }));
+  }
+
+  async function listPrComments(number) {
+    const { stdout } = await exec("gh", ["pr", "view", String(number), ...R, "--json", "comments"]);
+    return JSON.parse(stdout || "{}").comments || [];
+  }
+
+  function labelArgs({ add = [], remove = [] }) {
+    const args = [];
+    for (const name of add) args.push("--add-label", name);
+    for (const name of remove) args.push("--remove-label", name);
+    return args;
+  }
+
+  function setIssueLabels(number, delta) {
+    const args = labelArgs(delta);
+    if (args.length === 0) return Promise.resolve();
+    return exec("gh", ["issue", "edit", String(number), ...R, ...args]);
+  }
+
+  function setPrLabels(number, delta) {
+    const args = labelArgs(delta);
+    if (args.length === 0) return Promise.resolve();
+    return exec("gh", ["pr", "edit", String(number), ...R, ...args]);
+  }
+
+  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.
+  const restore = (n) => setIssueLabels(n, { add: [READY], remove: [RUNNING] });
+
+  const markPrReady = (n) => exec("gh", ["pr", "ready", String(n), ...R]);
+  const markPrDraft = (n) => exec("gh", ["pr", "ready", String(n), ...R, "--undo"]);
+
+  const commentIssue = (n, body) => exec("gh", ["issue", "comment", String(n), ...R, "--body", body]);
+  const commentPr = (n, body) => exec("gh", ["pr", "comment", String(n), ...R, "--body", body]);
+
+  async function listLabels() {
+    const { stdout } = await exec("gh", ["label", "list", ...R, "--json", "name", "--limit", "200"]);
+    return JSON.parse(stdout || "[]");
+  }
+
+  const createLabel = ({ name, color, description }) =>
+    exec("gh", ["label", "create", name, ...R, "--color", color, "--description", description]);
+
+  // Deliberately no approve and no merge: the supervisor never does either.
+  return {
+    listReadyIssues, listRunningIssues, listOpenPrs, listPrComments,
+    claim, restore, setIssueLabels, setPrLabels, markPrReady, markPrDraft,
+    commentIssue, commentPr, listLabels, createLabel,
+  };
+}
+
+// ---- tmux adapter -----------------------------------------------------------
+// Worker logs are a diagnostic, never a dependency: a caller that wires none
+// gets exactly the behaviour that existed before they did.
+const NO_WORKER_LOGS = { prepare: async () => null, diagnostics: async () => null };
+
+export function createTmux({ exec, session = SESSION, logs = NO_WORKER_LOGS }) {
+  // The window command is run by tmux via `/bin/sh -c`, so the issue number
+  // must never carry shell metacharacters. It is always a GitHub issue number,
+  // but validate anyway so interpolation can never become an injection vector.
+  function issueNumber(number) {
+    const n = Number(number);
+    if (!Number.isInteger(n) || n <= 0) {
+      throw new Error(`invalid issue number: ${number}`);
+    }
+    return n;
+  }
+
+  // tmux passes its command to /bin/sh, which then invokes interactive bash so
+  // the subscription-authenticated `ccode` alias is available. Quote every
+  // model-derived or recorded value before it crosses either shell boundary.
+  function shellQuote(value) {
+    return `'${String(value).replaceAll("'", `'"'"'`)}'`;
+  }
+
+  async function ensureSession() {
+    try {
+      await exec("tmux", ["has-session", "-t", session]);
+    } catch {
+      await exec("tmux", ["new-session", "-d", "-s", session, "-n", "supervisor"]);
+    }
+  }
+
+  async function listWindows(prefix) {
+    const { stdout } = await exec("tmux", ["list-windows", "-t", session, "-F", "#{window_name}"]);
+    const pattern = new RegExp(`^${prefix}-(\\d+)$`);
+    const set = new Set();
+    for (const line of stdout.split("\n")) {
+      const m = line.trim().match(pattern);
+      if (m) set.add(Number(m[1]));
+    }
+    return set;
+  }
+
+  const listWorkerIssues = () => listWindows("issue");
+  // Reviewer windows are a separate namespace so the reserved reviewer slot can
+  // never be consumed by — or borrowed for — implementation.
+  const listReviewIssues = () => listWindows("review");
+
+  // Callers validate their numbers before calling this, so an invalid number
+  // still throws synchronously rather than rejecting a returned promise.
+  // `tee` sees the pane's combined output, which is the whole point of the
+  // log; an unreserved log leaves the command byte-identical to a plain launch.
+  async function newWindow(role, number, name, command) {
+    const path = await logs.prepare(role, number);
+    const cmd = `bash -ic ${shellQuote(command)}${path ? ` 2>&1 | tee ${shellQuote(path)}` : ""}`;
+    return exec("tmux", ["new-window", "-t", session, "-n", name, cmd]);
+  }
+
+  function openWorker(number) {
+    const n = issueNumber(number);
+    // `ccode` is a bash alias (setup-agents.sh), not a binary — tmux runs the
+    // window command via a non-interactive shell that never sources .bashrc,
+    // so the alias would silently fail to resolve without `bash -ic`, which
+    // forces alias expansion regardless of login/interactive invocation.
+    const command = `ccode --print --permission-mode auto --model claude-opus-4-8 "/github-issue ${n}"`;
+    return newWindow("issue", n, `issue-${n}`, command);
+  }
+
+  // The reviewer is a read-only pass over an existing PR; the window is named
+  // for the issue so capacity accounting lines up with the managed issue set.
+  function openReviewer(number, prNumber) {
+    const i = issueNumber(number);
+    const p = issueNumber(prNumber);
+    const command = `ccode --print --permission-mode auto --model claude-opus-4-8 "/review-pr ${p}"`;
+    return newWindow("review", i, `review-${i}`, command);
+  }
+
+  // Suppress ONLY a confirmed "window absent" failure (idempotent close). Any
+  // other tmux failure (e.g. server down) propagates so the caller does not
+  // wrongly free the slot for a window that may still be alive.
+  async function closeWorker(number) {
+    const n = issueNumber(number);
+    try {
+      await exec("tmux", ["kill-window", "-t", `${session}:issue-${n}`]);
+    } catch (err) {
+      const msg = `${err.stderr || ""} ${err.message || ""}`;
+      if (/can.?t find window|no such window|window not found/i.test(msg)) return;
+      throw err;
+    }
+  }
+
+  return { ensureSession, listWorkerIssues, listReviewIssues, openWorker, openReviewer, closeWorker };
+}
+
+// ---- one poll cycle ---------------------------------------------------------
+// Reconciles managed issues, gates reviewed PRs, then fills free slots. Every
+// per-issue action is isolated in its own try/catch so one failure never skips
+// the rest of the poll; only a tmux inspection failure aborts before any
+// mutation, because capacity would otherwise be unknown. Usage is not consulted
+// here: Sentinel enforces limits by pausing this whole container, so no worker
+// is ever killed for usage reasons.
+export async function runOnce({
+  gh, tmux,
+  checkSetupReady = async () => true,
+  implementationSlots = IMPLEMENTATION_SLOTS,
+  reviewerSlots = REVIEWER_SLOTS,
+  log,
+  logs = NO_WORKER_LOGS,
+  runningIssues,
+  now = Date.now,
+}) {
+  await tmux.ensureSession();
+  const running = runningIssues !== undefined ? runningIssues : await gh.listRunningIssues();
+  const liveImpl = await tmux.listWorkerIssues();
+  const liveReview = await tmux.listReviewIssues();
+  const prs = await gh.listOpenPrs();
+
+  let implLive = liveImpl.size;
+  let reviewLive = liveReview.size;
+
+  // Phase state as this poll last knew it, updated in place by each transition
+  // so the exit condition below reflects the work just done.
+  const phases = new Map(running.map((issue) => [issue.number, phaseOf(issue.labels)]));
+  const { managed, problems } = resolveManagedPrs(running, prs);
+
+  // --- linkage ambiguity fails closed ---------------------------------------
+  for (const problem of problems) {
+    try {
+      await failClosed({ gh, issue: problem.issue, pr: problem.pr, message: problem.message, log });
+      phases.set(problem.issue.number, BLOCKED);
+    } catch (err) {
+      log(`linkage repair failed for #${problem.issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
+  // --- implementation reconciliation ----------------------------------------
+  // `agent-running` is durable, so completion is "the issue reached a phase",
+  // never "the label went away".
+  for (const issue of running) {
+    try {
+      const phase = phases.get(issue.number);
+      if (phase) {
+        if (liveImpl.has(issue.number)) {
+          await tmux.closeWorker(issue.number);
+          liveImpl.delete(issue.number);
+          implLive -= 1;
+          log(`Implementation for #${issue.number} finished (${phase}) — slot freed`);
+        }
+      } else if (!liveImpl.has(issue.number)) {
+        // Window gone with no phase reached: the workflow died. Group 1 has no
+        // repair worker, so this fails closed rather than silently stranding
+        // the issue outside the lifecycle's terminal states.
+        const match = managed.find((m) => m.issue.number === issue.number);
+        const pr = match ? match.pr : null;
+        // The pane took its output with it, so the reserved log is the only
+        // surviving evidence of why the worker died. It belongs in the comment
+        // that blocks the issue, where whoever picks it up looks first.
+        const diagnostics = await logs.diagnostics("issue", issue.number);
+        let message = `The implementation worker for #${issue.number} exited before reaching a review phase.`;
+        if (diagnostics) {
+          message += `${pr ? ` Its linked PR is ${pr.url}.` : ""}`
+            + `\n\nWorker log: \`${diagnostics.path}\`\n\n\`\`\`\n${diagnostics.tail}\n\`\`\``;
+        }
+        await failClosed({ gh, issue, pr, message, log });
+        phases.set(issue.number, BLOCKED);
+      }
+    } catch (err) {
+      log(`reconcile error for #${issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
+  // --- review reconciliation -------------------------------------------------
+  const needsReview = [];
+  for (const { issue, pr } of managed) {
+    try {
+      await mirrorLabels({ gh, issue, pr });
+      if (phases.get(issue.number) !== REVIEW) continue;
+
+      const checkedAt = now();
+      const comments = await gh.listPrComments(pr.number);
+      const marker = selectApplicableMarker(comments, {
+        issue: issue.number, pr: pr.number,
+        head: pr.headRefOid, base: pr.baseRefOid,
+        issueBody: issue.body, prBody: pr.body,
+      });
+      const plan = planVerdict({
+        marker,
+        checks: classifyChecks(pr.statusCheckRollup, checkedAt),
+        isDraft: pr.isDraft,
+      });
+      if (plan.action === "review") {
+        needsReview.push({ issue, pr });
+        continue;
+      }
+      const { phase } = await applyReviewPlan({
+        gh, issue, pr, plan, rollup: pr.statusCheckRollup, now: checkedAt, log,
+      });
+      phases.set(issue.number, phase);
+    } catch (err) {
+      log(`review error for #${issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
+  const ready = await gh.listReadyIssues();
+  const wantsLaunch = ready.length > 0 || needsReview.length > 0;
+  if (wantsLaunch && !await checkSetupReady()) {
+    log("Agent setup incomplete — pausing worker and reviewer launches");
+    return { done: false, implLive, reviewLive, started: 0, reviewsStarted: 0 };
+  }
+
+  // --- reviewer launches (oldest PR first) -----------------------------------
+  needsReview.sort((a, b) =>
+    String(a.pr.createdAt).localeCompare(String(b.pr.createdAt)) || a.issue.number - b.issue.number);
+  let reviewsStarted = 0;
+  for (const { issue, pr } of needsReview) {
+    if (reviewLive >= reviewerSlots) break;
+    // A reviewer already running for this issue holds the slot; it is counted
+    // in `reviewLive` and must not be relaunched.
+    if (liveReview.has(issue.number)) continue;
+    try {
+      // Reaching a launch here means an earlier reviewer left without gating
+      // the PR. Surface its log before the relaunch, because retention will
+      // eventually displace it and the relaunch itself explains nothing.
+      const diagnostics = await logs.diagnostics("review", issue.number);
+      if (diagnostics) {
+        log(`A previous reviewer for #${issue.number} (${pr.url}) left ${diagnostics.path}:\n${diagnostics.tail}`);
+      }
+      await tmux.openReviewer(issue.number, pr.number);
+      reviewLive += 1;
+      reviewsStarted += 1;
+      log(`Started reviewer for #${issue.number} (PR #${pr.number})`);
+    } catch (err) {
+      log(`failed to start reviewer for #${issue.number} (leaving for next poll): ${err.message}`);
+    }
+  }
+
+  // --- implementation launches ----------------------------------------------
+  let started = 0;
+  for (const n of ready) {
+    if (implLive >= implementationSlots) break;
+    let claimed = false;
+    try {
+      await gh.claim(n);
+      claimed = true;
+      await tmux.openWorker(n);
+      implLive += 1;
+      started += 1;
+      log(`Started worker for #${n}`);
+    } catch (err) {
+      const cleanup = [];
+      if (claimed) {
+        try { await gh.restore(n); } catch (cleanupError) { cleanup.push(`restore: ${cleanupError.message}`); }
+      }
+      log(`failed to start #${n} (leaving for next poll): ${err.message}${cleanup.length ? `; cleanup failed: ${cleanup.join(", ")}` : ""}`);
+    }
+  }
+
+  // Group 1 may exit once every managed issue rests in a terminal phase and
+  // nothing is queued or live. Merge and cleanup monitoring belong to later
+  // groups.
+  const settled = [...phases.values()].every((phase) => phase === BLOCKED || phase === MERGE_REVIEW);
+  const done = ready.length === 0 && implLive === 0 && reviewLive === 0 && settled;
+  return { done, implLive, reviewLive, started, reviewsStarted };
+}
+
+// ---- real-environment wiring ------------------------------------------------
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+async function resolveRepo(exec) {
+  const { stdout } = await exec("git", ["remote", "get-url", "origin"]);
+  const m = stdout.trim().match(/[:/]([^/]+\/[^/]+?)(?:\.git)?$/);
+  if (!m) throw new Error(`cannot parse repo from remote: ${stdout.trim()}`);
+  return m[1];
+}
+
+// Mint a short-lived GitHub App installation token (cached & re-minted by the
+// helper). `gh` does not auto-consume the App credential, so it is injected as
+// GH_TOKEN into the exec environment for every gh call.
+async function mintToken(repo) {
+  const { stdout } = await run(TOKEN_SCRIPT, [], {
+    env: { ...process.env, GITHUB_APP_REPO: repo },
+    maxBuffer: 1 << 20,
+  });
+  const token = stdout.trim();
+  if (!token) throw new Error("gh-app-token helper returned an empty token");
+  return token;
+}
+
+function ghExec(token) {
+  return makeExec({ ...process.env, GH_TOKEN: token });
+}
+
+// Prefix an orchestrator log line with an ISO 8601 UTC timestamp so lines can
+// be placed in time (and counted in poll cycles) during live diagnosis. `now`
+// is injectable purely so the format can be asserted deterministically.
+export function formatLogLine(message, now = new Date()) {
+  return `[orchestrator ${now.toISOString()}] ${message}`;
+}
+
+// Label bootstrap runs at startup against the resolved repository, never at
+// Docker build time — the image has neither a target repository nor runtime
+// credentials.
+async function bootstrapRepoLabels({ gh, log }) {
+  await ensureLabels({ listLabels: gh.listLabels, createLabel: gh.createLabel, log });
+}
+
+export async function main({
+  exec = makeExec(),
+  resolveRepo: resolve = resolveRepo,
+  acquireOwnership = acquireSupervisorOwnership,
+  mintToken: mint = mintToken,
+  authExec = ghExec,
+  createTmux: tmuxFactory = createTmux,
+  createWorkerLogs: workerLogsFactory = createWorkerLogs,
+  bootstrapLabels = bootstrapRepoLabels,
+  resolveContainerId: resolveContainer = resolveOwnContainerId,
+  createLeaseClient = createConfiguredLease,
+  runPoll = runOnce,
+  checkSetupReady = isAgentSetupReady,
+  sleepImpl = sleep,
+  log = (message) => console.log(formatLogLine(message)),
+} = {}) {
+  const repo = await resolve(exec);
+  const releaseOwnership = await acquireOwnership(repo);
+  const lease = createLeaseClient();
+  let containerId;
+  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.
+    const logs = workerLogsFactory({ exec, log });
+    const tmux = tmuxFactory({ exec, logs });
+
+    // Startup auth smoke test — fail fast with a clear message rather than
+    // silently churning on unauthenticated gh calls every poll.
+    try {
+      const token = await mint(repo);
+      await authExec(token)("gh", ["repo", "view", repo, "--json", "nameWithOwner", "-q", ".nameWithOwner"]);
+      log(`Authenticated as GitHub App for ${repo}`);
+    } catch (err) {
+      throw new Error(`GitHub App auth check failed: ${err.message}`);
+    }
+
+    // Idempotent: creates only missing labels and never edits an existing one.
+    // A permission or authentication failure here is fatal.
+    {
+      const token = await mint(repo);
+      await bootstrapLabels({ gh: createGitHub({ exec: authExec(token), repo }), log });
+    }
+
+    // Register the container Sentinel may pause. Registration is a lease, not
+    // an admission decision — but without it nothing enforces the usage
+    // thresholds, so a local or transport failure here is fatal rather than
+    // silently running unenforced.
+    try {
+      containerId = await resolveContainer();
+      const { status } = await lease.register(containerId);
+      log(`Managed container lease ${status} for ${containerId}`);
+    } catch (err) {
+      throw new Error(`managed-container registration failed: ${err.message}`);
+    }
+
+    // The startup registration above is the first poll's refresh; every later
+    // poll re-PUTs the same ID, well inside the five-minute lease. A failed PUT
+    // is retried by the next poll; Sentinel's lease rules handle a container
+    // that really died.
+    for (let firstPoll = true; ; firstPoll = false) {
+      if (!firstPoll) {
+        try {
+          await lease.register(containerId);
+        } catch (err) {
+          log(`lease heartbeat failed: ${err.message}`);
+        }
+      }
+      let result;
+      try {
+        const token = await mint(repo);
+        const gh = createGitHub({ exec: authExec(token), repo });
+        result = await runPoll({
+          gh, tmux, checkSetupReady,
+          implementationSlots: IMPLEMENTATION_SLOTS,
+          reviewerSlots: REVIEWER_SLOTS,
+          log, logs,
+        });
+      } catch (err) {
+        log(`poll error (continuing): ${err.message}`);
+        await sleepImpl(POLL_MS);
+        continue;
+      }
+      if (result.done) {
+        log("Queue empty and no live workers — stopping.");
+        return;
+      }
+      await sleepImpl(POLL_MS);
+    }
+  } finally {
+    // Best-effort only: correctness never depends on a clean exit, because
+    // Sentinel expires a stale running lease on its own.
+    if (containerId) {
+      try {
+        await lease.unregister(containerId);
+      } catch (err) {
+        log(`lease unregister failed (Sentinel lease expiry recovers this): ${err.message}`);
+      }
+    }
+    await releaseOwnership();
+  }
+}
+
+async function isDirectEntry() {
+  if (!process.argv[1]) return false;
+  const [modulePath, entryPath] = await Promise.all([
+    realpath(fileURLToPath(import.meta.url)),
+    realpath(process.argv[1]),
+  ]);
+  return modulePath === entryPath;
+}
+
+if (await isDirectEntry()) {
+  main().catch((err) => {
+    console.error(formatLogLine(`FATAL: ${err.message}`));
+    process.exitCode = 1;
+  });
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@nickysagan/issue-orchestrator",
+  "version": "0.1.0",
+  "description": "A small, supervised GitHub issue queue that keeps autonomous coding workers alive.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sadotu/issue-orchestrator.git"
+  },
+  "type": "module",
+  "bin": { "issue-orchestrator": "bin/supervisor.mjs" },
+  "files": ["bin", "src"],
+  "publishConfig": { "registry": "https://registry.npmjs.org", "access": "public" },
+  "scripts": {
+    "test": "node --test 'test/**/*.test.mjs'",
+    "start": "node bin/supervisor.mjs"
+  },
+  "engines": { "node": ">=20.8.0" }
+}