@nickysagan/issue-orchestrator 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nickysagan/issue-orchestrator",
-  "version": "0.1.2",
+  "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/repairGate.mjs

@@ -0,0 +1,57 @@
+import { BLOCKED, PHASE_LABELS, REVIEW, RUNNING } from "./labels.mjs";
+import { selectApplicableMarker } from "./reviewMarker.mjs";
+import {
+  selectLatestTrustedReview, selectLatestTrustedReviewContext,
+  selectRepairHistory, selectRepairReservation,
+} from "./repairMarker.mjs";
+
+export function exactPhase(labels, phase) {
+  const set = new Set(labels || []);
+  return set.has(RUNNING) && set.has(phase)
+    && PHASE_LABELS.filter((label) => set.has(label)).length === 1;
+}
+
+export function planRepair({ issue, pr, comments, phase, liveRepair, maxAttempts }) {
+  if (![BLOCKED, REVIEW].includes(phase)) return { action: "skip" };
+  if (!liveRepair && exactPhase(issue.labels, REVIEW) && exactPhase(pr.labels, REVIEW)) return { action: "skip" };
+
+  const identity = { issue: issue.number, pr: pr.number };
+  const history = selectRepairHistory(comments, identity);
+  const latestReview = selectLatestTrustedReview(comments, identity);
+  const latestContext = selectLatestTrustedReviewContext(comments, identity);
+  if (!history.valid) return { action: "invalid-history", history, latestReview };
+  const reservation = latestReview?.verdict === "BLOCKING"
+    ? selectRepairReservation(comments, identity, latestReview.fingerprint)
+    : null;
+  if (reservation) {
+    if (liveRepair) return { action: "live", reservation };
+    if (reservation.head !== pr.headRefOid) {
+      return { action: "review", reason: "reserved-head-changed", reservation };
+    }
+    return { action: "failed", reservation };
+  }
+  if (phase !== BLOCKED || !exactPhase(issue.labels, BLOCKED) || !exactPhase(pr.labels, BLOCKED)) {
+    return { action: "skip" };
+  }
+  const marker = selectApplicableMarker(comments, {
+    ...identity, head: pr.headRefOid, base: pr.baseRefOid,
+    issueBody: issue.body, prBody: pr.body,
+  });
+  const applicable = marker && latestReview
+    && marker.fingerprint === latestReview.fingerprint && marker.pass === latestReview.pass;
+  if (!applicable || marker.verdict !== "BLOCKING") {
+    return latestReview?.verdict === "BLOCKING"
+      ? { action: "review", reason: "stale-review-snapshot" }
+      : { action: "skip" };
+  }
+  if (!pr.isDraft) return { action: "skip" };
+  if (history.attempts.length >= maxAttempts) {
+    return { action: "budget", marker, history };
+  }
+  return {
+    action: "eligible", marker, history,
+    attempt: history.attempts.length + 1,
+    sourceFingerprint: marker.fingerprint,
+    blockingCreatedAt: latestContext?.createdAt,
+  };
+}

package/src/repairMarker.mjs

@@ -0,0 +1,248 @@
+import { parseReviewMarkers } from "./reviewMarker.mjs";
+
+export const REPAIR_MARKER_TAG = "issue-orchestrator:repair-attempt v1";
+
+const ATTEMPT_PATTERN = /^<!-- issue-orchestrator:repair-attempt v1 (\{.*\}) -->$/m;
+const ATTEMPT_FIELDS = ["issue", "pr", "attempt", "sourceFingerprint", "head", "log"];
+const FAILURE_FIELDS = ["issue", "pr", "attempt", "sourceFingerprint"];
+const BUDGET_FIELDS = ["issue", "pr", "sourceFingerprint"];
+const INVALID_HISTORY_FIELDS = ["issue", "pr", "sourceFingerprint"];
+const FAILURE_PATTERN = /^<!-- issue-orchestrator:repair-failure v1 (\{.*\}) -->$/m;
+const BUDGET_PATTERN = /^<!-- issue-orchestrator:repair-budget-exhausted v1 (\{.*\}) -->$/m;
+const INVALID_HISTORY_PATTERN = /^<!-- issue-orchestrator:repair-history-invalid v1 (\{.*\}) -->$/m;
+
+function positiveInteger(value) {
+  return Number.isInteger(value) && value > 0;
+}
+
+function validIdentity(value) {
+  return value && positiveInteger(value.issue) && positiveInteger(value.pr);
+}
+
+const fingerprint = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const commit = (value) => typeof value === "string" && /^[0-9a-f]{40}$/.test(value);
+
+function exactPayload(value, fields) {
+  return value && typeof value === "object" && !Array.isArray(value)
+    && Object.keys(value).length === fields.length
+    && fields.every((field) => Object.hasOwn(value, field));
+}
+
+function attemptPayload(value) {
+  if (!exactPayload(value, ATTEMPT_FIELDS)) return null;
+  if (!positiveInteger(value.issue) || !positiveInteger(value.pr) || !positiveInteger(value.attempt)) return null;
+  if (!fingerprint(value.sourceFingerprint) || !commit(value.head)) return null;
+  if (value.log !== null && (typeof value.log !== "string" || value.log.length === 0)) return null;
+  return Object.fromEntries(ATTEMPT_FIELDS.map((field) => [field, value[field]]));
+}
+
+export function parseRepairAttempt(body) {
+  const match = ATTEMPT_PATTERN.exec(String(body ?? ""));
+  if (!match) return null;
+  try {
+    return attemptPayload(JSON.parse(match[1]));
+  } catch {
+    return null;
+  }
+}
+
+function trustedAttempt(comment, identity) {
+  if (comment?.viewerDidAuthor !== true) return null;
+  const marker = parseRepairAttempt(comment.body);
+  if (!marker || marker.issue !== identity.issue || marker.pr !== identity.pr) return null;
+  return marker;
+}
+
+export function selectRepairReservation(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || typeof sourceFingerprint !== "string" || sourceFingerprint.length === 0) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    const marker = trustedAttempt(comment, identity);
+    if (marker?.sourceFingerprint === sourceFingerprint) found = marker;
+  }
+  return found;
+}
+
+function trustedReviews(comment, identity) {
+  if (comment?.viewerDidAuthor !== true) return [];
+  return parseReviewMarkers(comment.body).filter((marker) => (
+    marker.issue === identity.issue && marker.pr === identity.pr
+  ));
+}
+
+export function selectLatestTrustedReview(comments, identity) {
+  if (!validIdentity(identity)) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    for (const marker of trustedReviews(comment, identity)) found = marker;
+  }
+  return found;
+}
+
+export function selectLatestTrustedReviewContext(comments, identity) {
+  if (!validIdentity(identity)) return null;
+  let found = null;
+  for (const comment of comments || []) {
+    for (const marker of trustedReviews(comment, identity)) {
+      found = { marker, createdAt: comment.createdAt, url: comment.url };
+    }
+  }
+  return found;
+}
+
+export function selectRepairHistory(comments, identity) {
+  if (!validIdentity(identity)) return { valid: false, attempts: [], blockingPasses: [] };
+  const all = Array.from(comments || []);
+  let start = 0;
+  for (let index = 0; index < all.length; index += 1) {
+    if (trustedReviews(all[index], identity).some(({ verdict }) => verdict === "PASS")) start = index + 1;
+  }
+
+  const attempts = [];
+  const blockingPasses = [];
+  const blockingSources = new Set();
+  const attemptedSources = new Set();
+  let valid = true;
+  for (const comment of all.slice(start)) {
+    for (const marker of trustedReviews(comment, identity)) {
+      if (marker.verdict === "BLOCKING") {
+        blockingPasses.push({ fingerprint: marker.fingerprint, pass: marker.pass, url: comment.url });
+        blockingSources.add(`${marker.fingerprint}\0${marker.head}`);
+      }
+    }
+    const marker = trustedAttempt(comment, identity);
+    if (!marker) continue;
+    if (!blockingSources.has(`${marker.sourceFingerprint}\0${marker.head}`)) continue;
+    if (attemptedSources.has(marker.sourceFingerprint)) {
+      valid = false;
+      continue;
+    }
+    if (marker.attempt !== attempts.length + 1) {
+      valid = false;
+      continue;
+    }
+    attempts.push(marker);
+    attemptedSources.add(marker.sourceFingerprint);
+  }
+  return { valid, attempts, blockingPasses };
+}
+
+function hasTrustedMarker(comments, identity, pattern, fields, validPayload, matches) {
+  for (const comment of comments || []) {
+    if (comment?.viewerDidAuthor !== true) continue;
+    const match = pattern.exec(String(comment.body ?? ""));
+    if (!match) continue;
+    try {
+      const marker = JSON.parse(match[1]);
+      if (exactPayload(marker, fields) && validPayload(marker)
+        && marker.issue === identity.issue && marker.pr === identity.pr
+        && matches(marker)) return true;
+    } catch {
+      // Malformed comments are untrusted state, never durable evidence.
+    }
+  }
+  return false;
+}
+
+export function hasRepairFailure(comments, identity, attempt, sourceFingerprint) {
+  if (!validIdentity(identity) || !positiveInteger(attempt) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, FAILURE_PATTERN, FAILURE_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && positiveInteger(marker.attempt) && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.attempt === attempt && marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+export function hasRepairBudgetComment(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, BUDGET_PATTERN, BUDGET_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+export function hasInvalidRepairHistoryComment(comments, identity, sourceFingerprint) {
+  if (!validIdentity(identity) || !fingerprint(sourceFingerprint)) return false;
+  return hasTrustedMarker(
+    comments, identity, INVALID_HISTORY_PATTERN, INVALID_HISTORY_FIELDS,
+    (marker) => positiveInteger(marker.issue) && positiveInteger(marker.pr)
+      && fingerprint(marker.sourceFingerprint),
+    (marker) => marker.sourceFingerprint === sourceFingerprint,
+  );
+}
+
+function requireCommentInput(input, { attempt = false } = {}) {
+  if (!validIdentity(input)) throw new TypeError("issue and pr must be positive integers");
+  if (!fingerprint(input.sourceFingerprint)) {
+    throw new TypeError("sourceFingerprint must be 64 lowercase hex characters");
+  }
+  if (attempt && !positiveInteger(input.attempt)) throw new TypeError("attempt must be a positive integer");
+}
+
+function hidden(tag, payload) {
+  return `<!-- ${tag} ${JSON.stringify(payload)} -->`;
+}
+
+export function formatRepairAttemptComment(input) {
+  requireCommentInput(input, { attempt: true });
+  if (!commit(input.head)) throw new TypeError("head must be 40 hex characters");
+  if (input.log !== undefined && input.log !== null
+    && (typeof input.log !== "string" || input.log.length === 0)) {
+    throw new TypeError("log must be a nonempty string or null");
+  }
+  if (!positiveInteger(input.maxAttempts)) throw new TypeError("maxAttempts must be a positive integer");
+  const marker = {
+    issue: input.issue, pr: input.pr, attempt: input.attempt,
+    sourceFingerprint: input.sourceFingerprint, head: input.head,
+    log: input.log ?? null,
+  };
+  return [
+    `Automatic repair attempt ${input.attempt} of ${input.maxAttempts} reserved for review source \`${input.sourceFingerprint}\`.`,
+    "",
+    hidden(REPAIR_MARKER_TAG, marker),
+  ].join("\n");
+}
+
+export function formatRepairFailureComment(input) {
+  requireCommentInput(input, { attempt: true });
+  const details = [];
+  if (input.exitCode !== undefined) details.push(`Exit code ${input.exitCode}.`);
+  if (typeof input.logUrl === "string" && input.logUrl.length > 0) details.push(`Logs: ${input.logUrl}`);
+  else details.push("Log location unavailable.");
+  return [
+    `Automatic repair attempt ${input.attempt} failed for review source \`${input.sourceFingerprint}\`.`,
+    ...details,
+    "",
+    hidden("issue-orchestrator:repair-failure v1", {
+      issue: input.issue, pr: input.pr, attempt: input.attempt, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}
+
+export function formatRepairBudgetComment(input) {
+  requireCommentInput(input);
+  if (!positiveInteger(input.maxAttempts)) throw new TypeError("maxAttempts must be a positive integer");
+  const urls = Array.from(input.blockingReviewUrls || []).filter((url) => typeof url === "string" && url.length > 0);
+  return [
+    `${input.maxAttempts} automatic repair attempts have been exhausted for review source \`${input.sourceFingerprint}\`.`,
+    ...(urls.length > 0 ? ["", "Blocking review passes:", ...urls.map((url) => `- ${url}`)] : []),
+    "",
+    hidden("issue-orchestrator:repair-budget-exhausted v1", {
+      issue: input.issue, pr: input.pr, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}
+
+export function formatInvalidRepairHistoryComment(input) {
+  requireCommentInput(input);
+  return [
+    `Invalid automatic repair history detected for review source \`${input.sourceFingerprint}\`. Manual intervention is required.`,
+    "",
+    hidden("issue-orchestrator:repair-history-invalid v1", {
+      issue: input.issue, pr: input.pr, sourceFingerprint: input.sourceFingerprint,
+    }),
+  ].join("\n");
+}

package/src/reviewGate.mjs

@@ -1,4 +1,4 @@
-import { BLOCKED, MANAGED_LABELS, MERGE_REVIEW, REVIEW, phaseOf } from "./labels.mjs";
+import { BLOCKED, MANAGED_LABELS, MERGE_REVIEW, PHASE_LABELS, REVIEW, phaseOf } from "./labels.mjs";
 
 const BRANCH_PREFIX = /^agent\/(\d+)-/;
 
@@ -188,13 +188,23 @@ 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.
-async function setPhase({ gh, issue, pr, phase }) {
-  const current = phaseOf(issue.labels);
-  if (current === phase) return;
-  const delta = { add: [phase], remove: current ? [current] : [] };
-  await gh.setIssueLabels(issue.number, delta);
-  if (pr) await gh.setPrLabels(pr.number, delta);
+// 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 || []);
+    return {
+      add: current.has(phase) ? [] : [phase],
+      remove: PHASE_LABELS.filter((label) => label !== phase && current.has(label)),
+    };
+  };
+  const issueDelta = deltaFor(issue.labels);
+  if (issueDelta.add.length || issueDelta.remove.length) await gh.setIssueLabels(issue.number, issueDelta);
+  if (pr) {
+    if (!Array.isArray(pr.labels)) throw new Error("PR labels must be provided");
+    const prDelta = deltaFor(pr.labels);
+    if (prDelta.add.length || prDelta.remove.length) await gh.setPrLabels(pr.number, prDelta);
+  }
 }
 
 export async function mirrorLabels({ gh, issue, pr }) {

package/src/workerLogs.mjs

@@ -1,9 +1,8 @@
 // Durable per-attempt worker logs.
 //
-// A tmux worker's output lives and dies with its pane, so a window that
-// vanishes takes the only evidence of why with it. Every launch reserves a
-// file here and streams its combined output into it, which lets the supervisor
-// surface a bounded, redacted tail when it later notices the worker is gone.
+// A tmux worker's pane output disappears with its window. Every launch reserves
+// a file here and streams its combined output into it, preserving evidence the
+// supervisor can surface as a bounded, redacted tail after the worker is gone.
 //
 // Everything is best effort: a log that cannot be written must never cost a
 // worker, so every operation degrades to `null` rather than throwing.
@@ -26,7 +25,7 @@ export const TAIL_CHARS = 4000;
 // Roles are an allowlist, not a passthrough: a later repair worker adds one
 // string here and needs no other change, while no caller-supplied value can
 // ever reach the path.
-export const WORKER_ROLES = new Set(["issue", "review"]);
+export const WORKER_ROLES = new Set(["issue", "review", "repair"]);
 
 const REDACTIONS = [
   // Whole PEM blocks first, before any inner rule can fragment them. The body
@@ -154,9 +153,10 @@ export function createWorkerLogs({
     return join(dir, `${id.role}-${id.number}.${attempt}.log`);
   }
 
-  // The newest recorded attempt for a worker, with its tail already bounded and
-  // redacted. `null` when there is nothing to show — including on any read
-  // failure, because diagnostics must never break the poll that surfaces them.
+  // The newest recorded attempt for a worker, with its attempt number and its
+  // tail already bounded and redacted. `null` when there is nothing to show —
+  // including on any read failure, because diagnostics must never break the
+  // poll that surfaces them.
   async function diagnostics(role, number) {
     const id = identity(role, number);
     if (!id) return null;
@@ -164,8 +164,12 @@ export function createWorkerLogs({
       const dir = await logDir();
       const attempts = await existingAttempts(dir, id.role, id.number);
       if (attempts.length === 0) return null;
-      const path = join(dir, attempts.at(-1).name);
-      return { path, tail: boundedTail(await readFile(path, "utf8")) };
+      const newest = attempts.at(-1);
+      const path = join(dir, newest.name);
+      // The attempt number is this worker's durable launch count: retention
+      // prunes the *oldest* files while `prepare` numbers from the highest
+      // surviving one, so it keeps rising past `KEEP_ATTEMPTS`.
+      return { path, attempt: newest.attempt, tail: boundedTail(await readFile(path, "utf8")) };
     } catch {
       return null;
     }