elanous 0.2.15 → 0.2.16

package/src/self-implement/heal-triage.ts

@@ -156,6 +156,50 @@ export interface HealTriageResult {
   readonly evidence: readonly string[];
 }
 
+/** 수리 한도를 다 쓴 런의 결함 셋. 힐 루프가 이 셋 중 하나만 고른다. */
+export type ReworkCapDefectClass = 'test-defect' | 'goal-defect' | 'code-defect';
+
+/** 분류 뒤 힐 루프가 고르는 다음 행동. */
+export type ReworkCapNextAction = 'harvest' | 'relaunch' | 'card';
+
+export interface ReworkCapHealInput {
+  /** 게이트가 이번 diff 가 들여온 실패 수. 없으면 0. */
+  readonly introduced?: readonly string[];
+  /** 마지막 리뷰 must-fix. 없으면 빈 목록. */
+  readonly mustFix?: readonly string[];
+  readonly summary?: string;
+}
+
+export interface ReworkCapHealDecision {
+  readonly defectClass: ReworkCapDefectClass;
+  readonly nextAction: ReworkCapNextAction;
+  readonly evidence: readonly string[];
+}
+
+const GOAL_DEFECT = /골|goal|acceptance|수용 기준|요구가 모순|스펙|경계:/i;
+
+/**
+ * 수리 한도 소진 런을 «시험 결함 · 골 결함 · 코드 결함» 중 하나로 가르고
+ * 수확·재발사·카드 중 하나를 고른다. 근거는 게이트 introduced 목록과 마지막 리뷰 지적이다.
+ * 도입 실패가 있으면 코드 결함(재발사). 리뷰가 골·수용 기준을 짚으면 골 결함(카드).
+ * 그 밖(리뷰만 있거나 근거가 비면)은 시험 결함(수확)이다.
+ */
+export function classifyReworkCapExhaustion(input: ReworkCapHealInput): ReworkCapHealDecision {
+  const introduced = (input.introduced ?? []).map((item) => item.trim()).filter(Boolean);
+  const mustFix = (input.mustFix ?? []).map((item) => item.trim()).filter(Boolean);
+  const evidence = [
+    ...introduced.map((item) => `gate introduced: ${item}`),
+    ...mustFix.map((item) => `review must-fix: ${item}`),
+  ];
+  if (introduced.length > 0) {
+    return { defectClass: 'code-defect', nextAction: 'relaunch', evidence };
+  }
+  if (mustFix.some((item) => GOAL_DEFECT.test(item)) || (input.summary ? GOAL_DEFECT.test(input.summary) : false)) {
+    return { defectClass: 'goal-defect', nextAction: 'card', evidence };
+  }
+  return { defectClass: 'test-defect', nextAction: 'harvest', evidence };
+}
+
 const UNTESTABLE_EXT = new Set(['.md', '.json', '.yaml', '.yml', '.txt']);
 const ENVIRONMENT_CLAIM = /할당량|자격|기판|quota|credential|substrate/i;
 

package/src/self-implement/orchestrator.ts

@@ -66,9 +66,11 @@ import { appendRunLedgerEntry, loadRunLedger, parseRunShardIdentity, queryRunCha
 import { emitSessionEvent, type SessionEventInput } from '../context-bus/session-events.js';
 import { decideLineageSupersede, lineageSupersedeCloseComment, type LineageSupersedeOpenDraft } from './lineage-supersede.js';
 import { basename, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
 import { enqueueControlMemo, readSoftStopRequestStatus, type SoftStopRequestRead } from '../harness/control-inbox.js';
 import { debug } from '../debug/log.js';
 import { recordFailureEvent } from './heal-intake.js';
+import { classifyReworkCapExhaustion, type ReworkCapHealDecision } from './heal-triage.js';
 import { releasePathHold, releasePathHoldComment, RELEASE_PATH_LABEL } from '../self-dev/release-path-guard.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { reworkDecision } from './decision-events.js';
@@ -101,6 +103,26 @@ import { elanousStateRoot } from '../autopilot/state-paths.js';
 import { addNextMdReleaseNote, harnessReleaseNote, parseReleaseNoteSection, releaseNotesDir, renderReleaseNoteSection, writeReleaseNote, type ReleaseNoteFragment, type ReleaseNoteSection } from '../release-loop/release-note.js';
 import { landingFreezeMessage } from '../release-loop/landing-freeze.js';
 import { admitLandingMerge, owningRepoRoot } from './frozen-merges.js';
+import { recordFollowUpOnMerge, type FollowUpMergeInput, type FollowUpSeams } from './follow-up-goals.js';
+
+/** Merge result and exit stay untouched: a draft failure is one debug line. */
+async function draftFollowUpAfterMerge(input: FollowUpMergeInput, followUp: FollowUpSeams | undefined): Promise<void> {
+  try {
+    await recordFollowUpOnMerge(input, {
+      ...(followUp ? {
+        ...(followUp.mode ? { mode: followUp.mode } : {}),
+        ...(followUp.readDrafts ? { readDrafts: followUp.readDrafts } : {}),
+        ...(followUp.appendDraft ? { appendDraft: followUp.appendDraft } : {}),
+        ...(followUp.enqueue ? { enqueue: followUp.enqueue } : {}),
+        ...(followUp.cellOwner ? { cellOwner: followUp.cellOwner } : {}),
+        ...(followUp.stateRoot ? { stateRoot: followUp.stateRoot } : {}),
+      } : {}),
+      log: (category, event, data) => { debug.log(category, event, data); },
+    });
+  } catch (error) {
+    debug.log('self-implement.follow-up', 'draft-failed', { prNumber: input.prNumber, error: error instanceof Error ? error.message : String(error) });
+  }
+}
 import { plannedSelfImplBranch } from '../harness/worktree-branch-prefix.js';
 export { slugifyFeature } from '../harness/worktree-branch-prefix.js';
 import { AUTO_REVIEW_LABEL, resolveAutoReviewLabels } from './context-capsule.js';
@@ -1056,7 +1078,7 @@ export interface SelfImplementSeams {
   /** PR 생성 뒤 런의 라운드 대화를 게시한다. 실패는 PR 개설을 되돌리지 않는다. */
   postPrComment?: (opts: { number: number; body: string; cwd: string }) => Promise<void>;
   addPrLabel?: (opts: { number: number; label: string; cwd: string }) => Promise<void>;
-  readPrFiles?: (opts: { number: number; cwd: string }) => Promise<string[]>;
+  readPrFiles?: (opts: { number: number; cwd: string; base?: string }) => Promise<string[]>;
   /** PR의 base/head SHA와 관측된 PR base를 한 응답에서 고정한다. 미주입·실패·빈 SHA면 검사 대상을 증명할 수 없어 fail-closed로 PR을 열어 둔다. */
   readPrCommitShas?: (opts: { number: number; cwd: string }) => Promise<{ baseCommit: string; headCommit: string; baseRefName?: string }>;
   /** 고정한 base/head SHA 쌍의 unified diff. 가변 PR 조회를 다시 사용하면 ABA head 변경에 안전하지 않으므로 두 SHA는 필수 입력이다. */
@@ -1090,6 +1112,12 @@ export interface SelfImplementSeams {
     readRunLedger?: (runId: string) => RunLedgerEntry[] | null | Promise<RunLedgerEntry[] | null>;
     closeDraft: (input: { number: number; comment: string }) => void | Promise<void>;
   };
+  /**
+   * FOLLOWUP-LOOP① — after a successful merge, leftover findings become one follow-up draft.
+   * Tests inject every store. Omission writes nothing (no operational ledger, no queue).
+   * Production `defaultSeams` fills the state-root ledger and, only in `live`, the harness queue.
+   */
+  followUp?: FollowUpSeams;
   /** ⑥ HITL 게이트 — PR open 전 승인. ★fail-closed: 생략/false 면 PR 안 열림(자동 승인 없음). review 동봉
    *  (2026-07-21) — HITL 이 리뷰 verdict 를 보고 판단, auto 모드는 verdict 로 자동 결정. */
   approvePr?: (summary: { branch: string; gateLog?: string; implSummary: string; review?: SelfImplementReview }) => Promise<boolean>;
@@ -3394,7 +3422,26 @@ function mergeDecisionEvidenceCoverage(evidenceCoverage: {
     : { evidenceCoverageMeasured: false };
 }
 
+function installedBuildForOrigin(env: NodeJS.ProcessEnv): { installedVersion: string; installedCommit: string } {
+  const root = env.ELANOUS_TEST_HOME?.trim()
+    ? join(env.ELANOUS_TEST_HOME.trim(), '.local/share/elanous')
+    : join(homedir(), '.local/share/elanous');
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(join(root, 'install.json'), 'utf8'));
+    if (typeof parsed !== 'object' || parsed === null) return { installedVersion: 'unknown', installedCommit: 'unknown' };
+    const version = (parsed as { version?: unknown }).version;
+    const commit = (parsed as { commit?: unknown }).commit;
+    return {
+      installedVersion: typeof version === 'string' && version.trim() ? version.trim() : 'unknown',
+      installedCommit: typeof commit === 'string' && commit.trim() ? commit.trim() : 'unknown',
+    };
+  } catch {
+    return { installedVersion: 'unknown', installedCommit: 'unknown' };
+  }
+}
+
 function runOriginData(env: NodeJS.ProcessEnv = process.env): RunOriginData {
+  const installed = installedBuildForOrigin(env);
   return {
     hostId: resolveHostId(env),
     hostname: hostname(),
@@ -3403,6 +3450,8 @@ function runOriginData(env: NodeJS.ProcessEnv = process.env): RunOriginData {
     substrate: env.ELANOUS_SUBSTRATE || 'host',
     instance: resolveInstanceName(),
     elanousVersion: (JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version: string }).version,
+    installedVersion: installed.installedVersion,
+    installedCommit: installed.installedCommit,
     ...(env.ELANOUS_POD_NAME ? { podName: env.ELANOUS_POD_NAME } : {}),
     ...(env.ELANOUS_NODE_NAME ? { nodeName: env.ELANOUS_NODE_NAME } : {}),
     ...(env.ELANOUS_POD_NAMESPACE ? { podNamespace: env.ELANOUS_POD_NAMESPACE } : {}),
@@ -3616,6 +3665,7 @@ export async function runSelfImplement(opts: SelfImplementOptions): Promise<Self
     },
   } satisfies LogSink);
   let traversalFinalized = false;
+  reworkCapProceed = false;
   const progressDelivery = { delivered: 0, unwired: 0, callbackFailed: 0 };
   let capturedPrNumber: number | undefined;
   let openPrInvoked = false;
@@ -4179,10 +4229,31 @@ export async function runSelfImplement(opts: SelfImplementOptions): Promise<Self
     const terminalStage = terminalResult?.stage ?? 'crashed';
     try {
       const mappedStatus = mapStageToRunStatus(terminalStage)?.runStatus;
-      if (!terminalResult || mappedStatus === 'failed' || (mappedStatus === undefined && terminalResult.ok === false) || signalIncompleteState(roundClassifications).latestSignalIncomplete) {
+      const reworkCapStop = terminalResult?.stage === 'pr-opened' && (
+        terminalResult.outcome === 'budget-exhausted'
+        || (terminalResult.outcome === 'completed' && reworkCapProceed)
+      );
+      if (!terminalResult || mappedStatus === 'failed' || (mappedStatus === undefined && terminalResult.ok === false) || signalIncompleteState(roundClassifications).latestSignalIncomplete || reworkCapStop) {
+        const reworkCap = reworkCapStop ? classifyReworkCapExhaustion({
+          introduced: terminalResult?.gate?.reflectGateFacts?.introduced
+            ? [`introduced=${terminalResult.gate.reflectGateFacts.introduced}`]
+            : [],
+          mustFix: terminalResult?.review?.mustFix ?? terminalResult?.mustFix,
+          summary: terminalResult?.review?.summary,
+        }) : undefined;
+        if (reworkCap) {
+          observeOuter('rework-cap-heal', {
+            stage: terminalStage,
+            defectClass: reworkCap.defectClass,
+            nextAction: reworkCap.nextAction,
+            evidence: reworkCap.evidence,
+          });
+        }
         recordFailureEvent({
-          source: 'harness-run', kind: terminalStage, ref: runId,
-          summary: opts.feature.split(/\r?\n/, 1)[0]?.trim() || `Harness run ${runId} failed`,
+          source: 'harness-run', kind: reworkCapStop ? 'rework-cap-exhausted' : terminalStage, ref: runId,
+          summary: reworkCap
+            ? reworkCapFailureSummary(opts.feature, reworkCap)
+            : opts.feature.split(/\r?\n/, 1)[0]?.trim() || `Harness run ${runId} failed`,
           at: new Date().toISOString(),
         });
       }
@@ -4544,6 +4615,14 @@ function observeRunRollup(
   }, effectiveOutcome.runStatus === 'failed' ? { level: 'warn' } : undefined);
 }
 
+let reworkCapProceed = false;
+
+function reworkCapFailureSummary(feature: string, decision: ReworkCapHealDecision): string {
+  const title = feature.split(/\\r?\\n/, 1)[0]?.trim() || 'rework cap exhausted';
+  const evidence = decision.evidence.length ? decision.evidence.join(' | ') : 'no gate introduced list and no review finding';
+  return `${title} [${decision.defectClass} → ${decision.nextAction}] ${evidence}`;
+}
+
 async function runSelfImplementInner(
   opts: SelfImplementOptions,
   identity?: { runId: string; source: ReturnType<typeof resolveRunIdentity>['source'] },
@@ -5030,6 +5109,8 @@ async function runSelfImplementInner(
   } | undefined;
   let gate!: SelfImplementGateResult;
   let review: SelfImplementReview | undefined;
+  /** Review-budget leftovers and the body that carried them, so a later merge drafts from the same text. */
+  let preparedReviewBudgetPrBody: string | undefined;
   const reviewMustFixCountHistory: number[] = [];
   const reviewMustFixTrend = (): string => {
     if (reviewMustFixCountHistory.length < 2) return '아직 못 잰다';
@@ -5365,6 +5446,23 @@ async function runSelfImplementInner(
       observe('pr.comment.seam-missing', { number: pr.number, buffered: prCommentBuffer.length }, { level: 'warn' });
       return;
     }
+    const marker = '<!-- elanous:run-status -->';
+    if (s.findPrComment && s.editPrComment) {
+      try {
+        const existing = await s.findPrComment({ number: pr.number, marker, cwd: wt.path });
+        const history = prCommentBuffer.join('\n\n');
+        const body = existing
+          ? existing.body.includes('</details>')
+            ? existing.body.replace(/<\/details>(?![\s\S]*<\/details>)/, `\n\n${history}\n</details>`)
+            : `${existing.body}\n\n<details>\n<summary>Round history</summary>\n\n${history}\n</details>`
+          : `${marker}\n<details>\n<summary>Round history</summary>\n\n${history}\n</details>`;
+        if (existing) await s.editPrComment({ id: existing.id, body, cwd: wt.path });
+        else await s.postPrComment({ number: pr.number, body, cwd: wt.path });
+      } catch (error) {
+        // Unknown lookup/edit outcome is not proof of absence: never create a second status comment.
+        observe('pr.comment.status-failed', { number: pr.number, error: error instanceof Error ? error.message : String(error) }, { level: 'warn' });
+      }
+    }
     for (const body of prCommentBuffer) {
       try {
         await s.postPrComment({ number: pr.number, body, cwd: wt.path });
@@ -5798,6 +5896,7 @@ async function runSelfImplementInner(
       'self-implement-review-budget-pr',
       followUpMustFix,
     );
+    preparedReviewBudgetPrBody = preparedPrBody.body;
     const pr = await withStepTimeout(s.openPr({
       title: prTitle(opts.feature),
       body: preparedPrBody.body,
@@ -6211,6 +6310,7 @@ async function runSelfImplementInner(
           if (budgetDecision.stop) {
             if (budgetDecision.exit === 'proceed') {
               finalizeSupervisorDeliveries('supervisor-rework-proceed');
+              if (round > effectiveMax) reworkCapProceed = true;
               break;
             }
             finalizeSupervisorDeliveries('supervisor-rework-blocked');
@@ -6271,12 +6371,25 @@ async function runSelfImplementInner(
       if (isReviewRework(reworkKind)) {
         if (reflectRejectedAudit.length && review) review.shouldFix = [...review.shouldFix, ...reflectRejectedAudit];
         const reason = `review must-fix unresolved after ${round - 1} rework round(s)`;
+        // Pod keeps review-blocked work as a labelled draft (or aborts with the preserved branch) instead of
+        // accepting the review budget into a non-draft PR — restored after #24341 (0.2.16 gate shard 5).
         if (!podReviewBlockedDraft) {
           const acceptance = await acceptReviewBudget(
             review?.mustFix ?? [],
             reworkParts.some((part) => part.source === 'supervisor'),
           );
           if (acceptance.decision.action === 'accept') {
+            if (acceptance.pr) {
+              await draftFollowUpAfterMerge({
+                prNumber: acceptance.pr.number,
+                followUpMustFix: acceptance.decision.unresolvedMustFix,
+                shouldFix: review?.shouldFix,
+                prBody: preparedReviewBudgetPrBody,
+                feature: opts.feature,
+                ...(opts.goalId ? { cellId: opts.goalId } : {}),
+                ...(opts.goalFile ? { goalFile: opts.goalFile } : {}),
+              }, s.followUp);
+            }
             return {
               ok: true,
               stage: 'pr-opened',
@@ -7523,11 +7636,15 @@ async function runSelfImplementInner(
   let releasePathInspectionError: string | undefined;
   if (s.readPrFiles) {
     try {
-      const files = await withStepTimeout(s.readPrFiles({ number: pr.number, cwd: wt.path }), T.pr, 'pr');
+      // Rate-limit recovery may wait up to 15 minutes for X-RateLimit-Reset; the PR step cap must not cut that wait.
+      const files = await s.readPrFiles({ number: pr.number, cwd: wt.path, ...(opts.base ? { base: opts.base } : {}) });
       if (!Array.isArray(files) || !files.every((path) => typeof path === 'string')) throw new Error('invalid PR file list');
       releaseHoldPath = releasePathHold(files);
     } catch (error) {
-      releasePathInspectionError = safeErrorDescription(error);
+      const rateLimited = error instanceof Error && (error as { rateLimited?: boolean }).rateLimited === true;
+      releasePathInspectionError = rateLimited
+        ? `rate-limit: ${safeErrorDescription(error)}`
+        : safeErrorDescription(error);
     }
   } else if (canAuto || labels?.includes(AUTO_REVIEW_LABEL)) {
     releasePathInspectionError = 'readPrFiles seam unavailable';
@@ -7566,7 +7683,9 @@ async function runSelfImplementInner(
   if (releasePathInspectionError && (canAuto || labels?.includes(AUTO_REVIEW_LABEL))) {
     observe('release-path-inspection-failed', { number: pr.number, error: releasePathInspectionError }, { level: 'error' });
     canAuto = false;
-    mergeSkipReason = mergeReason = 'release-path-inspection-failed';
+    mergeSkipReason = mergeReason = releasePathInspectionError.startsWith('rate-limit:')
+      ? 'release-path-inspection-failed: rate-limit'
+      : 'release-path-inspection-failed';
     recordMergeDecision();
     progress('pr-opened', `OP 승인 대기 (#${pr.number}): PR 경로 조회 실패`);
     return { ok: true, stage: 'pr-opened', node: 'open-pr', ...resolveRunOutcome({ termination: 'completed' }), ...decisionSignalResult, ...preservedCompletionResult, ...(completionStatus ? { completionStatus } : {}), sessionId, worktreePath: wt.path, branch: wt.branch, gate, ...(review ? { review } : {}), mergeReason, prUrl: pr.url, prNumber: pr.number };
@@ -7700,6 +7819,18 @@ async function runSelfImplementInner(
         prNumber: pr.number,
         openedAt: openedAtFromLedger(mergedLedger, new Date().toISOString()),
       }, observe);
+      // FOLLOWUP-LOOP① — leftover findings become one follow-up draft. Failure is a log line only;
+      // this return (stage, merged, exit via ok) stays the merge result.
+      await draftFollowUpAfterMerge({
+        prNumber: pr.number,
+        // 정상 병합은 리뷰를 통과한 뒤라 미해결 must-fix 가 없다 — 남은 것은 should-fix ⊕ PR 본문 «남은 조각».
+        // 미해결 must-fix 는 리뷰 예산 수락 경로가 직접 넘긴다(위 acceptance 분기).
+        shouldFix: review?.shouldFix,
+        prBody: [preparedReviewBudgetPrBody, preparedPrBody.body].filter(Boolean).join('\n'),
+        feature: opts.feature,
+        ...(opts.goalId ? { cellId: opts.goalId } : {}),
+        ...(opts.goalFile ? { goalFile: opts.goalFile } : {}),
+      }, s.followUp);
       return { ok: true, stage: 'merged', node: 'merge', ...resolveRunOutcome({ termination: 'completed' }), ...decisionSignalResult, ...preservedCompletionResult, ...(completionStatus ? { completionStatus } : {}), sessionId, worktreePath: wt.path, branch: wt.branch, gate, ...(review ? { review } : {}), merged: true, ...(mergedBase ? { mergedBase } : {}), prUrl: pr.url, prNumber: pr.number };
     }
     progress('pr-opened', `병합 실패 — PR 개설됨(#${pr.number}·수동 병합). ${m.detail ?? ''}`);

package/src/self-implement/run-ledger.ts

@@ -94,6 +94,10 @@ export interface RunOriginData extends Record<string, unknown> {
   substrate: string;
   instance: string;
   elanousVersion: string;
+  /** install.json version. 못 읽으면 «unknown». */
+  installedVersion: string;
+  /** install.json commit. 못 읽으면 «unknown». */
+  installedCommit: string;
   podName?: string;
   nodeName?: string;
   podNamespace?: string;

package/src/self-implement/seams.ts

@@ -24,6 +24,9 @@ import { isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { promisify } from 'node:util';
 import { forkSessionById, HARNESS_SESSION_ORIGIN, isHarnessSessionOrigin } from '../session/index.js';
 import { configuredWorktreeRoot, getUserConfig, resolveRoleLlm } from '../user-config.js';
+import { elanousStateRoot } from '../autopilot/state-paths.js';
+import { addHarnessQueue } from '../harness/harness-queue.js';
+import { readFollowUpMode } from './follow-up-goals.js';
 import { getProviderForConfig } from '../llm.js';
 import { createWorktree, DEFAULT_BRANCH_WORKTREE_BASE, linkWorktreeDependencies, removeWorktree, resolveDefaultBranchBase, resolveMainRepoRoot } from '../git-fs/worktree.js';
 import { isWorktreeInUse, listActiveTerminalDirectories } from '../harness/harness-clean.js';
@@ -77,7 +80,8 @@ import { tscEnv, assessTypecheckExecution, classifyTypecheckErrors, diffTypechec
 import { nestCapReached, childNestEnv, nestInfo } from '../agent/nest-depth.js';
 import { harnessBoundaryEnv, harnessBoundaryRequestsEnv, harnessBoundaryResponsesEnv, harnessSpaceEnv, getHarnessSpace, normalizeSpaceId, getHarnessRunId, resolveRunIdentity } from '../harness/harness-space.js';
 import { debug } from '../debug/log.js';
-import { RELEASE_PATH_HOLD_MARKER, RELEASE_PATH_LABEL, releasePathHoldShouldPost, releasePathHoldCommentsArgs, releasePrFilePaths } from '../self-dev/release-path-guard.js';
+import { RELEASE_PATH_HOLD_MARKER, RELEASE_PATH_LABEL, releasePathHoldShouldPost, releasePathHoldCommentsArgs } from '../self-dev/release-path-guard.js';
+import { readPrFilesWithRateLimitFallback, runGhApp } from './app-api-budget.js';
 import { emitDecision } from '../live/detail-switch.js';
 import { gateDecision, reviewDecision, mergeDecision } from './decision-events.js';
 import { LogStore } from '../mss/logging/log-store.js';
@@ -110,6 +114,10 @@ declare module './orchestrator.js' {
     /** PR close(+브랜치 삭제). 기본 구성은 PrManager.closePr 위임(같은 인자·같은 반환).
      *  오케스트레이터는 아직 부르지 않는다 — 그 배선은 조각 ②다. */
     closePr?: (prUrl: string, comment?: string) => boolean;
+    /** Find an issue comment on this PR by its body marker; absence is distinct from a failed lookup. */
+    findPrComment?: (opts: { number: number; marker: string; cwd: string; comments?: unknown }) => Promise<{ id: number; body: string } | undefined>;
+    /** Replace an existing PR issue comment by ID, using the same GitHub App identity as postPrComment. */
+    editPrComment?: (opts: { id: number; body: string; cwd: string }) => Promise<void>;
   }
 }
 import { harnessPolicyEnv } from './harness-policy.js';
@@ -1415,6 +1423,11 @@ export function defaultSeams(o: DefaultSeamsOptions = {}): SelfImplementSeams {
       const { supersedeMergedGoalDrafts } = await import('../harness/harness-cli-command.js');
       await supersedeMergedGoalDrafts(number, cwd);
     },
+    followUp: {
+      mode: readFollowUpMode(),
+      stateRoot: elanousStateRoot(),
+      enqueue: (item) => addHarnessQueue({ seat: item.seat, say: item.say, idempotencyKey: item.idempotencyKey }),
+    },
     lineageSupersede: {
       listOpenDrafts: () => listOpenDraftsForLineage(),
       readRunLedger: (runId) => {
@@ -2394,46 +2407,62 @@ export function defaultSeams(o: DefaultSeamsOptions = {}): SelfImplementSeams {
     postPrComment: async ({ number, body, cwd }) => {
       // Round comments go out as the GitHub App like the PR itself — a personal `gh` login made the owner a
       // participant and mailed them on merge (#22089).
-      if (body.startsWith(RELEASE_PATH_HOLD_MARKER)) {
+        if (body.startsWith(RELEASE_PATH_HOLD_MARKER)) {
         // Several merge surfaces may hold the same PR; post the release-path hold comment once.
         let history: unknown;
         try {
-          history = JSON.parse((await execFileAsync('gh', releasePathHoldCommentsArgs(number), {
+          history = JSON.parse((await runGhApp('post-pr-comment-history', releasePathHoldCommentsArgs(number), {
             cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env: ghAutomationEnv(process.env),
           })).stdout);
         } catch { history = undefined; }
         if (!releasePathHoldShouldPost(() => history)) return;
       }
-      await execFileAsync('gh', ['pr', 'comment', String(number), '--body', body], {
+      await runGhApp('post-pr-comment', ['pr', 'comment', String(number), '--body', body], {
+        cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env: ghAutomationEnv(process.env),
+      });
+    },
+
+    findPrComment: async ({ number, marker, cwd, comments }) => {
+      const pages: unknown = comments ?? JSON.parse((await runGhApp('find-pr-comment', releasePathHoldCommentsArgs(number), {
+        cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env: ghAutomationEnv(process.env),
+      })).stdout);
+      if (!Array.isArray(pages)) throw new Error('gh api PR comments returned an invalid list');
+      const entries = pages.flatMap((page: unknown) => Array.isArray(page) ? page : [page]);
+      for (const entry of entries) {
+        if (!entry || typeof entry !== 'object' || !('body' in entry) || typeof entry.body !== 'string'
+          || !('id' in entry) || typeof entry.id !== 'number' || !Number.isSafeInteger(entry.id) || entry.id <= 0) {
+          throw new Error('gh api PR comments returned an invalid comment');
+        }
+      }
+      return entries.find((entry: { id: number; body: string }) => entry.body.includes(marker));
+    },
+
+    editPrComment: async ({ id, body, cwd }) => {
+      await runGhApp('edit-pr-comment', ['api', '--method', 'PATCH', `repos/{owner}/{repo}/issues/comments/${id}`, '-f', `body=${body}`], {
         cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env: ghAutomationEnv(process.env),
       });
     },
 
     addPrLabel: async ({ number, label, cwd }) => {
       if (label === RELEASE_PATH_LABEL) {
-        const existing = await execFileAsync('gh', ['label', 'list', '--search', label, '--json', 'name'], {
+        const existing = await runGhApp('add-pr-label-list', ['label', 'list', '--search', label, '--json', 'name'], {
           cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, env: ghAutomationEnv(process.env),
         });
         const names: unknown = JSON.parse(existing.stdout);
         if (!Array.isArray(names)) throw new Error('gh label list returned an invalid list');
         if (!names.some((item: unknown) => !!item && typeof item === 'object' && 'name' in item && item.name === label)) {
-          await execFileAsync('gh', ['label', 'create', label, '--color', 'D93F0B', '--description', 'Release path requires OP approval'], {
+          await runGhApp('add-pr-label-create', ['label', 'create', label, '--color', 'D93F0B', '--description', 'Release path requires OP approval'], {
             cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, env: ghAutomationEnv(process.env),
           });
         }
       }
-      await execFileAsync('gh', ['pr', 'edit', String(number), '--add-label', label], {
+      await runGhApp('add-pr-label', ['pr', 'edit', String(number), '--add-label', label], {
         cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, env: ghAutomationEnv(process.env),
       });
     },
-    readPrFiles: async ({ number, cwd }) => {
-      // Paginate the PR file API: a single `gh pr view --json files` can omit files after the first page.
-      const { stdout } = await execFileAsync('gh', [
-        'api', '--paginate', '--slurp', '--method', 'GET', '-f', 'per_page=100',
-        `repos/{owner}/{repo}/pulls/${number}/files`,
-      ], { cwd, encoding: 'utf8', timeout: GIT_TIMEOUT, maxBuffer: 64 * 1024 * 1024, env: ghAutomationEnv(process.env) });
-      return releasePrFilePaths(JSON.parse(stdout));
-    },
+    readPrFiles: async ({ number, cwd, base }) => readPrFilesWithRateLimitFallback({
+      number, cwd, env: ghAutomationEnv(process.env), ...(base ? { base } : {}),
+    }),
 
     ...(o.approvePr ? { approvePr: o.approvePr } : {}),
 

package/src/session-runtime/index.ts

@@ -66,6 +66,8 @@ export {
 export {
   fetchApiWithRetry,
   ApiHttpError,
+  OverloadFailoverError,
+  recordLlmCallOutcome,
   type FetchApiWithRetryOpts,
 } from './retry-api.js';
 

package/src/session-runtime/retry-api.ts

@@ -25,6 +25,8 @@ import {
   decideRetry,
   DoomLoopTracker,
   fingerprintError,
+  llmCallOutcomeKind,
+  type LlmCallOutcomeKind,
   type RetryAction,
 } from './retry-policy.js';
 
@@ -75,6 +77,35 @@ export interface FetchApiWithRetryOpts {
    *  row" pattern within a single request. Pass a session-scoped
    *  tracker if you want cross-request doom detection. */
   doomTracker?: DoomLoopTracker;
+  /** Fallbacks still unused. When > 0, k consecutive overload-class
+   *  failures throw OverloadFailoverError before another retry sleep. */
+  remainingFallbacks?: number;
+}
+
+/** Raised when overload repeats k times and a fallback is still unused.
+ *  The caller switches provider; this is not a retry exhaustion. */
+export class OverloadFailoverError extends Error {
+  readonly provider: string;
+  readonly status: number;
+  readonly kind: LlmCallOutcomeKind;
+  readonly streak: number;
+  readonly cause: unknown;
+
+  constructor(opts: {
+    provider: string;
+    status: number;
+    kind: LlmCallOutcomeKind;
+    streak: number;
+    cause: unknown;
+  }) {
+    super(`overload failover after ${opts.streak} ${opts.kind} from ${opts.provider} (status ${opts.status})`);
+    this.name = 'OverloadFailoverError';
+    this.provider = opts.provider;
+    this.status = opts.status;
+    this.kind = opts.kind;
+    this.streak = opts.streak;
+    this.cause = opts.cause;
+  }
 }
 
 /** POST a fetch with the standard retry policy. On 2xx returns the
@@ -91,13 +122,17 @@ export async function fetchApiWithRetry(
 ): Promise<Response> {
   const maxAttempts = opts.maxAttempts ?? 4;
   const tracker = opts.doomTracker ?? new DoomLoopTracker();
+  const remainingFallbacks = opts.remainingFallbacks ?? 0;
   let attempt = 0;
+  let overloadStreak = 0;
   let lastErr: unknown;
   while (attempt < maxAttempts) {
     let response: Response | null = null;
     try {
       response = await fetch(url, init);
       if (response.ok) {
+        recordLlmCallOutcome(opts.provider, response.status, 'ok');
+        overloadStreak = 0;
         return response;
       }
       // Drain body so the error can carry the API's explanation. We
@@ -136,6 +171,11 @@ export async function fetchApiWithRetry(
       // would couple the helper to the caller's signal.
       if (isAbortLike(err)) throw err;
 
+      const status = err instanceof ApiHttpError ? err.status : 0;
+      const kind = llmCallOutcomeKind(status, err instanceof Error ? err.message : String(err));
+      recordLlmCallOutcome(opts.provider, status, kind);
+      if (kind === 'overloaded' || kind === '5xx' || kind === 'rate-limit') overloadStreak += 1;
+      else overloadStreak = 0;
       const fp = fingerprintError(err, `api:${opts.provider}`);
       const doomStatus = tracker.record(fp);
       const retryAfter = err instanceof ApiHttpError ? err.retryAfter : undefined;
@@ -143,6 +183,8 @@ export async function fetchApiWithRetry(
         attempt,
         doomStatus,
         retryAfter,
+        remainingFallbacks,
+        overloadStreak,
       });
       debug.log('llm.retry', decisionEvent(decision.action), {
         provider: opts.provider,
@@ -151,7 +193,19 @@ export async function fetchApiWithRetry(
         reason: decision.reason,
         delayMs: decision.delayMs,
         status: err instanceof ApiHttpError ? err.status : undefined,
+        kind,
+        overloadStreak,
+        remainingFallbacks,
       });
+      if (decision.action === 'switch-provider') {
+        throw new OverloadFailoverError({
+          provider: opts.provider,
+          status,
+          kind,
+          streak: overloadStreak,
+          cause: err,
+        });
+      }
       if (decision.action !== 'retry') {
         throw err;
       }
@@ -172,6 +226,39 @@ export async function fetchApiWithRetry(
   throw lastErr ?? new Error(`${opts.errorPrefix}: retry loop terminated unexpectedly`);
 }
 
+type OutcomeWriter = (row: { provider: string; status: number; kind: LlmCallOutcomeKind }) => void;
+
+let outcomeWriterForTesting: OutcomeWriter | undefined;
+
+/** Test seam. Production uses the log store. `undefined` restores it. */
+export function setLlmCallOutcomeWriterForTesting(writer: OutcomeWriter | undefined): void {
+  outcomeWriterForTesting = writer;
+}
+
+/** The one event launch failover is allowed to read.
+ *  Category `llm.call`, event `outcome`, payload {provider,status,kind}.
+ *  Written straight to the log store — `debug.log` drops the row when no
+ *  sink is armed, which is the normal launch path. */
+export function recordLlmCallOutcome(provider: string, status: number, kind: LlmCallOutcomeKind): void {
+  const data = { provider, status, kind };
+  // Trace only — a store sink would otherwise write a second `llm.call`/`outcome` row and halve the streak threshold.
+  debug.log('llm.call', 'outcome-trace', data);
+  if (outcomeWriterForTesting) {
+    outcomeWriterForTesting(data);
+    return;
+  }
+  if (process.env.NODE_ENV === 'test') return;
+  try {
+    const { getDefaultLogStore } = require('../mss/logging/log-store.js') as typeof import('../mss/logging/log-store.js');
+    getDefaultLogStore()?.insertBatch([{
+      rec: { ts: new Date().toISOString(), category: 'llm.call', event: 'outcome', data },
+      surface: 'llm',
+    }]);
+  } catch {
+    // A failed observation must not fail the call. Launch then sees no sample.
+  }
+}
+
 function decisionEvent(action: RetryAction): string {
   // Stable category names for log filtering. The action is the most
   // useful axis ("how many turns hit retry vs abort"); the category