@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/review/review-loop.js

@@ -4,7 +4,6 @@
  * Handles autonomous review loop orchestration.
  */
 
-const os = require('os');
 const fs = require('fs');
 const path = require('path');
 const fmt = require('../core/fmt');
@@ -12,20 +11,20 @@ const { git, run } = require('../core/git');
 const { findMissionDir, resolveWorktree, missionBranchName } = require('../core/mission-utils');
 const { resolveTaskFile, getTaskImplementer, getTaskStatus, enforceTaskAssignee, transitionTask, reportTaskResolution } = require('../tools/backlog');
 const { toVirtual, transitionVirtual } = require('../core/state-map');
-const { getPrStatus, readToken, getLatestReviewForPr, getLatestDispositionForPr, providerAvailable, getComments, postComment, postReview, closePr, resolveReviewUser, isProviderEnabled } = require('./review-adapter');
+const { getPrStatus, readToken, getLatestReviewForPr, getLatestDispositionForPr, providerAvailable, getComments, postComment, postReview, resolveReviewUser, isProviderEnabled } = require('./review-adapter');
 const { buildAutonomousReviewMatrix, formatMatrixSummary } = require('../core/runtime-matrix');
 const { buildReviewPrompt, buildActOnReviewPrompt, buildCompactReviewPrompt, buildCompactActOnReviewPrompt } = require('./review-prompts');
 const { ReviewState, readReviewState, writeReviewState, resetReviewState, VALID_PHASES } = require('./review-state');
-const { createEvent, consumeHumanNotes, VALID_EVENT_TYPES } = require('./review-events');
+
 const { workflowLauncherStatus, startAgent, eligibleAgentsForStep, selectAgent } = require('../agents/agents');
 const { performHandoff } = require('../commands/handoff');
 const { commitSafeMissionArtifacts, rebaseBeforeReviewRound } = require('./rebase');
 const { resolveAgentModel } = require('../core/product-config');
 
 // Import from review-polling module
-const { POLL_TIMEOUT, delay, resolvePollIntervalMs, resolvePollTimeoutMs, formatElapsed, isPollTimeout, pollForReview, pollForDisposition } = require('./review-polling');
+const { delay, resolvePollIntervalMs, resolvePollTimeoutMs, formatElapsed, isPollTimeout, pollForReview, pollForDisposition } = require('./review-polling');
 // Import from review-artifacts module
-const { buildMetadataFooter, reviewArtifactPath, resolveArtifactDir, readArtifactFile, deleteArtifactFile, normalizeReviewVerdict, normalizeDisposition, postWorkflowComment, postWorkflowReview, consumeReviewerArtifacts, consumeImplementerArtifacts } = require('./review-artifacts');
+const { buildMetadataFooter, resolveArtifactDir, consumeReviewerArtifacts, consumeImplementerArtifacts } = require('./review-artifacts');
 const stats = require('../commands/stats');
 const { resolveStageTelemetry } = require('../agents/stage-telemetry');
 
@@ -40,6 +39,11 @@ const { resolveStageTelemetry } = require('../agents/stage-telemetry');
 // one launch at a time, de-duped via review-state metadata, so Claude/custom rows
 // are cumulative too. A family switch creates a separate row instead of mixing
 // agents in one record.
+/**
+ * @param {string} agentFamily
+ * @param {{sessionId?: string, startedAt?: string, endedAt?: string, status?: number}} result
+ * @returns {string}
+ */
 function stageLaunchFingerprint(agentFamily, result) {
   return [
     String(agentFamily || '').trim().toLowerCase(),
@@ -50,29 +54,43 @@ function stageLaunchFingerprint(agentFamily, result) {
   ].join('|');
 }
 
-function markStageLaunchRecorded(state, { stage, agentFamily, result, slug, worktree, writeReviewStateFn = writeReviewState } = {}) {
-  if (!state || !agentFamily) return true;
+/**
+ * @param {Object|null} state
+ * @param {{stage: string, agentFamily: string, result?: {[key: string]: any}, slug: string, worktree?: string, writeReviewStateFn?: Function}} opts
+ * @returns {boolean}
+ */
+function markStageLaunchRecorded(state, /** @type {{stage: string, agentFamily: string, result?: {[key: string]: any}, slug: string, worktree?: string, writeReviewStateFn?: Function}} */ opts) {
+  const { stage, agentFamily, result, slug, worktree, writeReviewStateFn = writeReviewState } = opts || {};
+  if (!state || !agentFamily) {return true;}
   const key = stageWindowKey(stage, agentFamily);
-  const fingerprint = stageLaunchFingerprint(agentFamily, result);
-  const recordedStageLaunches = state.metadata && typeof state.metadata === 'object'
-    ? (state.metadata.recordedStageLaunches || {})
+  const fingerprint = stageLaunchFingerprint(agentFamily, /** @type {{sessionId?: string, startedAt?: string, endedAt?: string, status?: number}} */ (result));
+  /** @type {{[key: string]: any}} */
+  const stateObj = /** @type {{[key: string]: any}} */ (state);
+  const recordedStageLaunches = stateObj.metadata && typeof stateObj.metadata === 'object'
+    ? (stateObj.metadata.recordedStageLaunches || {})
     : {};
   const recorded = Array.isArray(recordedStageLaunches[key]) ? recordedStageLaunches[key] : [];
   if (recorded.includes(fingerprint)) {
     return false;
   }
-  if (!state.metadata || typeof state.metadata !== 'object') {
-    state.metadata = {};
+  if (!stateObj.metadata || typeof stateObj.metadata !== 'object') {
+    stateObj.metadata = {};
   }
-  state.metadata.recordedStageLaunches = {
-    ...(state.metadata.recordedStageLaunches || {}),
+  stateObj.metadata.recordedStageLaunches = {
+    ...(stateObj.metadata.recordedStageLaunches || {}),
     [key]: [...recorded, fingerprint].slice(-20),
   };
   writeReviewStateFn(slug, state, worktree);
   return true;
 }
 
-function recordStageStatsSafe(kind, { stage, slug, rootDir, worktree, implementer, reviewer, result, sinceMs, log, error, state, writeReviewStateFn = writeReviewState, model = null }) {
+/**
+ * @param {'review'|'active'} kind
+ * @param {{stage: string, slug: string, rootDir?: string, worktree?: string, implementer?: string, reviewer?: string, result?: {[key: string]: any}, sinceMs?: number, log?: Function, state?: {[key: string]: any}, writeReviewStateFn?: Function, model?: string|null}} opts
+ * @returns {void}
+ */
+function recordStageStatsSafe(kind, { stage, slug, rootDir, worktree, implementer, reviewer, result, sinceMs, log, state, writeReviewStateFn = writeReviewState, model = null }) {
+  /** @type {number} */
   let durationMinutes = 0;
   if (result && result.startedAt && result.endedAt) {
     durationMinutes = (Date.parse(result.endedAt) - Date.parse(result.startedAt)) / 60000;
@@ -81,10 +99,10 @@ function recordStageStatsSafe(kind, { stage, slug, rootDir, worktree, implemente
   // prefer the windowed Codex rollout, else the launcher-attached telemetry so
   // Claude active/review stages record real tokens instead of all-zeros
   // (task-1274), bounded to this stage by sinceMs (task-1285 F6).
-  const telemetry = resolveStageTelemetry({ worktree, result, sinceMs });
+  const telemetry = resolveStageTelemetry({ worktree: /** @type {string} */ (worktree || ''), result: /** @type {{[key: string]: any}} */ (result || {}), sinceMs: (/** @type {number | undefined} */ (sinceMs)) || 0 });
   try {
     const actorFamily = kind === 'review' ? reviewer : implementer;
-    if (state && !markStageLaunchRecorded(state, {
+    if (state && actorFamily && !markStageLaunchRecorded(state, {
       stage,
       agentFamily: actorFamily,
       result,
@@ -94,16 +112,17 @@ function recordStageStatsSafe(kind, { stage, slug, rootDir, worktree, implemente
     })) {
       return;
     }
-    stats.accumulateStageStats({ stage, slug, rootDir, implementer, reviewer, telemetry, durationMinutes, model });
-  } catch (err) {
+    /** @type {any} */ (stats).accumulateStageStats({ stage, slug, rootDir, implementer, reviewer, telemetry, durationMinutes, model });
+  } catch (/** @type {unknown} */ err) {
     // Best-effort: never escalate to the fatal `error` channel.
-    log(fmt.status('WARN', `Could not record ${kind} stats for ${slug}: ${err.message}`));
+    log?.(fmt.status('WARN', `Could not record ${kind} stats for ${slug}: ${/** @type {Error} */(err).message}`));
   }
 }
 
 const DEFAULT_MAX_ATTEMPTS = 5;
 const CONTINUE_SKIP_CHECK_TIMEOUT_MS = 10_000;
 
+/** @param {string} earlierIso @param {number} [nowMs] */
 function strictlyLaterIso(earlierIso, nowMs = Date.now()) {
   const earlierMs = Date.parse(earlierIso);
   if (!Number.isFinite(earlierMs)) {
@@ -116,6 +135,7 @@ function strictlyLaterIso(earlierIso, nowMs = Date.now()) {
 // Pre-review Setup Functions
 // ============================================================================
 
+/** @param {string} rootDir @param {{commandRunner?: Function, log?: Function}} [options] */
 function maybeUpdateGraphifyBeforeReview(rootDir, { commandRunner = run, log = fmt.log.plain } = {}) {
   const updateGraphifyKnowledgeGraph = require('../core/mission-utils').updateGraphifyKnowledgeGraph;
   return updateGraphifyKnowledgeGraph({
@@ -137,18 +157,12 @@ function maybeUpdateGraphifyBeforeReview(rootDir, { commandRunner = run, log = f
 // fallback identity selected by the launcher.
 // This helper detects the fallback, persists the new identity to review state
 // and the Backlog assignee, and returns the identity that should be polled for.
-function applyAgentFallback({
-  role,
-  original,
-  launchResult,
-  state,
-  slug,
-  worktree,
-  taskResolution,
-  log = fmt.log.plain,
-  writeReviewStateFn = writeReviewState,
-  enforceTaskAssigneeFn = enforceTaskAssignee
-} = {}) {
+/**
+ * @param {{role: string, original: string, launchResult?: {[key: string]: any}, state: {[key: string]: any}, slug: string, worktree?: string, taskResolution?: {[key: string]: any}, log?: Function, writeReviewStateFn?: Function, enforceTaskAssigneeFn?: Function}} opts
+ * @returns {string}
+ */
+function applyAgentFallback(/** @type {{role: string, original: string, launchResult?: {[key: string]: any}, state: {[key: string]: any}, slug: string, worktree?: string, taskResolution?: {[key: string]: any}, log?: Function, writeReviewStateFn?: Function, enforceTaskAssigneeFn?: Function}} */ opts) {
+  const { role, original, launchResult, state, slug, worktree, taskResolution, log = fmt.log.plain, writeReviewStateFn = writeReviewState, enforceTaskAssigneeFn } = opts;
   if (!launchResult || !launchResult.agent || launchResult.agent === original) {
     return original;
   }
@@ -161,13 +175,20 @@ function applyAgentFallback({
   }
   writeReviewStateFn(slug, state, worktree);
   if (role === 'implementer' && taskResolution && taskResolution.ok) {
-    if (!enforceTaskAssigneeFn(taskResolution.taskFile, fallback)) {
+    if (enforceTaskAssigneeFn && !enforceTaskAssigneeFn(taskResolution.taskFile, fallback)) {
       log(fmt.status('WARN', `Could not enforce fallback implementer ${fallback} in backlog task.`));
     }
   }
   return fallback;
 }
 
+/**
+ * @param {string} slug
+ * @param {{[key: string]: any}} state
+ * @param {string} worktree
+ * @param {{log?: Function, writeReviewStateFn?: Function}} [options]
+ * @returns {void}
+ */
 function persistNormalizedPhaseRepair(slug, state, worktree, { log = fmt.log.plain, writeReviewStateFn = writeReviewState } = {}) {
   if (!state || !state.phaseOriginal || VALID_PHASES.includes(state.phaseOriginal)) {
     return;
@@ -177,6 +198,7 @@ function persistNormalizedPhaseRepair(slug, state, worktree, { log = fmt.log.pla
   state.phaseOriginal = null;
 }
 
+/** @param {string} stage @param {string} agentFamily */
 function stageWindowKey(stage, agentFamily) {
   const normalizedStage = String(stage || 'default').trim().toLowerCase() || 'default';
   const normalizedAgent = String(agentFamily || '').trim().toLowerCase();
@@ -190,6 +212,7 @@ function stageWindowKey(stage, agentFamily) {
 // instead of re-summing a cumulative-since-first-launch window every round.
 // Resume-idempotency is provided separately by the launch fingerprint in
 // markStageLaunchRecorded, so the window itself does not need to persist.
+/** @param {{startedAt?: string}} result */
 function stageLaunchSinceMs(result) {
   const startedAt = result && result.startedAt ? String(result.startedAt) : '';
   const startedMs = startedAt ? Date.parse(startedAt) : NaN;
@@ -200,6 +223,11 @@ function stageLaunchSinceMs(result) {
 // Main Review Loop
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{implementer?: string, reviewer?: string, focus?: string, maxAttempts?: number, dryRun?: boolean, reset?: boolean, continue?: boolean, isContinue?: boolean, verbose?: boolean, pollTimeoutSeconds?: number|null, worktree?: string, missionPath?: string, resetReviewStateFn?: Function, maybeUpdateGraphifyBeforeReviewFn?: Function, readReviewStateFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, getTaskStatusFn?: Function, transitionTaskFn?: Function, toVirtualFn?: Function, transitionVirtualFn?: Function, workflowLauncherStatusFn?: Function, buildAutonomousReviewMatrixFn?: Function, formatMatrixSummaryFn?: Function, selectAgentFn?: Function, providerAvailableFn?: Function, runFn?: Function, getPrStatusFn?: Function, enforceTaskAssigneeFn?: Function, resolveReviewUserFn?: Function, forgejoAvailableFn?: Function, resolveForgejoUserFn?: Function, readTokenFn?: Function, getCommentsFn?: Function, postCommentFn?: Function, postReviewFn?: Function, writeReviewStateFn?: Function, startAgentFn?: Function, pollForReviewFn?: Function, pollForDispositionFn?: Function, applyAgentFallbackFn?: Function, buildReviewPromptFn?: Function, buildActOnReviewPromptFn?: Function, buildCompactReviewPromptFn?: Function, buildCompactActOnReviewPromptFn?: Function, consumeReviewerArtifactsFn?: Function, consumeImplementerArtifactsFn?: Function, rebaseBeforeReviewRoundFn?: Function, eligibleAgentsForStepFn?: Function, performHandoffFn?: Function, log?: Function, error?: Function, getLatestReviewForPrFn?: Function, getLatestDispositionForPrFn?: Function, sleepFn?: Function, exit?: Function, gitFn?: Function, isReviewProviderEnabledFn?: Function, legacyIsForgejoReviewEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, recordStageStatsSafeFn?: Function}} [opts]
+ * @returns {Promise<void>}
+ */
 async function startReviewLoop(slug, opts = {}) {
   let {
     implementer,
@@ -268,7 +296,7 @@ async function startReviewLoop(slug, opts = {}) {
   isContinue = Boolean(isContinue || continueFlag);
 
   const pollIntervalMs = resolvePollIntervalMs();
-  const pollTimeoutMs = resolvePollTimeoutMs(pollTimeoutSeconds);
+  const pollTimeoutMs = resolvePollTimeoutMs(/** @type {number} */ (pollTimeoutSeconds || 0));
 
   const worktree = callerWorktree || resolveWorktree(slug) || process.cwd();
   const resolvedProviderAvailableFn = providerAvailableFn || forgejoAvailableFn || providerAvailable;
@@ -285,7 +313,7 @@ async function startReviewLoop(slug, opts = {}) {
   // slug-derived default). Absent the flag, `effectiveMissionPath` stays
   // undefined and the prompts fall back to the standard slug-derived path.
   const missionDir = findMissionDir(slug, worktree, { missionPath });
-  let effectiveMissionPath;
+  let effectiveMissionPath = /** @type {string|null} */ (null);
   if (missionPath && fs.existsSync(missionPath)) {
     effectiveMissionPath = fs.statSync(missionPath).isDirectory()
       ? path.join(missionPath, 'MISSION.md')
@@ -385,9 +413,9 @@ async function startReviewLoop(slug, opts = {}) {
       // PR exists. Only fall back to guidance when self-heal cannot yield an open PR.
       // Emits `--push` (the command self-heal attempts and the correct manual
       // equivalent) — never the old, frequently-wrong `--submit`.
-      const fallbackGuidance = (reason) => {
+      const fallbackGuidance = (/** @type {string|null} */ reason) => {
         error(fmt.status('FAIL', `No open review PR found for ${branch}. Create the PR before starting the review loop.`));
-        if (reason) error(`       Handoff failure: ${reason}`);
+        if (reason) {error(`       Handoff failure: ${reason}`);}
         error(`       Run: px review ${slug} --push`);
       };
 
@@ -441,7 +469,7 @@ async function startReviewLoop(slug, opts = {}) {
   // Resolve reviewer after the no-PR/self-heal gate so implementation-phase
   // guidance does not depend on workstation launcher availability.
   let reviewerSource = 'explicit';
-  let selectErr = null;
+  /** @type {Error|null} */ let selectErr = null;
   if (!reviewer) {
     if (persisted && persisted.reviewer) {
       reviewer = persisted.reviewer;
@@ -450,16 +478,16 @@ async function startReviewLoop(slug, opts = {}) {
     } else {
       try {
         reviewer = selectAgentFn('review', { exclude: new Set([implementer]) });
-      } catch (err) {
-        selectErr = err;
-        reviewer = null;
+      } catch (/** @type {unknown} */ err) {
+        selectErr = /** @type {Error} */ (err);
+        reviewer = undefined;
       }
       reviewerSource = 'auto-derived';
     }
   }
 
   if (!reviewer) {
-    const anyDifferentFamilyRunnable = agents.some(a => a !== implementer && workflowLauncherStatusFn(a).supported);
+    const anyDifferentFamilyRunnable = agents.some((/** @type {string} */ a) => a !== implementer && workflowLauncherStatusFn(a).supported);
     const implementerRunnable = agents.includes(implementer) && workflowLauncherStatusFn(implementer).supported;
     if (!anyDifferentFamilyRunnable && implementerRunnable) {
       log(fmt.status('WARN', `No supported different-family reviewer found for implementer "${implementer}".`));
@@ -468,7 +496,7 @@ async function startReviewLoop(slug, opts = {}) {
       reviewerSource = 'single-family-fallback';
     } else if (!anyDifferentFamilyRunnable) {
       if (!forgejoEnabled) {
-        const detail = selectErr ? `: ${selectErr.message}` : '';
+const detail = selectErr ? `: ${(/** @type {Error} */ (selectErr)).message}` : '';
         reviewer = 'autonomous';
         reviewerSource = 'fallback';
         log(fmt.status('WARN', `No reviewer could be auto-derived${detail}; defaulting to "autonomous"`));
@@ -479,7 +507,7 @@ async function startReviewLoop(slug, opts = {}) {
         const reason = selectErr ? `: ${selectErr.message}` : '';
         error(fmt.status('FAIL', `No reviewer could be auto-derived${reason}.`));
         error('\n' + fmt.status('INFO', 'Full runtime matrix:'));
-        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => error(`  ${line}`));
+        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => error(`  ${line}`));
         error('\n' + fmt.status('FAIL', `No runnable reviewer route for implementer "${implementer}".`));
         exit(1);
         return;
@@ -512,7 +540,7 @@ async function startReviewLoop(slug, opts = {}) {
         error(`       Looked for: ${reviewerStatus.detail}`);
       }
       error('\n' + fmt.status('INFO', 'Full runtime matrix:'));
-      formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => error(`  ${line}`));
+      formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => error(`  ${line}`));
       error('\n' + fmt.status('FAIL', `No runnable reviewer route for implementer "${implementer}".`));
       exit(1);
       return;
@@ -521,7 +549,7 @@ async function startReviewLoop(slug, opts = {}) {
     if (!agents.includes(reviewer)) {
       error(fmt.status('FAIL', `Unsupported reviewer: "${reviewer}" (blocked or unsupported).`));
       error('\n' + fmt.status('INFO', 'Full runtime matrix:'));
-      formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => error(`  ${line}`));
+      formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => error(`  ${line}`));
       error('\n' + fmt.status('FAIL', `No runnable reviewer route for implementer "${implementer}".`));
       exit(1);
       return;
@@ -534,9 +562,9 @@ async function startReviewLoop(slug, opts = {}) {
       if (reviewerSource === 'explicit') {
         const reason = !agents.includes(reviewer) ? 'blocked or unsupported' : 'launcher is not available';
         error(fmt.status('FAIL', `Unsupported reviewer: "${reviewer}" (${reason}).`));
-        if (reviewerStatus.detail) error(`       Looked for: ${reviewerStatus.detail}`);
+        if (reviewerStatus.detail) {error(`       Looked for: ${reviewerStatus.detail}`);}
         error('\n' + fmt.status('INFO', 'Full runtime matrix:'));
-        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => error(`  ${line}`));
+        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => error(`  ${line}`));
         error('\n' + fmt.status('FAIL', `No runnable reviewer route for implementer "${implementer}".`));
         exit(1);
         return;
@@ -553,13 +581,13 @@ async function startReviewLoop(slug, opts = {}) {
         } else {
           fallbackStatus = workflowLauncherStatusFn(fallback);
         }
-      } catch (err) {
+      } catch (/** @type {unknown} */ err) {
         fallback = null;
         fallbackStatus = null;
       }
 
       if (!fallback) {
-        const anyDifferentFamilyRunnable = agents.some(a => a !== implementer && workflowLauncherStatusFn(a).supported);
+    const anyDifferentFamilyRunnable = agents.some((/** @type {string} */ a) => a !== implementer && workflowLauncherStatusFn(a).supported);
         const implementerRunnable = agents.includes(implementer) && workflowLauncherStatusFn(implementer).supported;
         if (!anyDifferentFamilyRunnable && implementerRunnable) {
           log(fmt.status('WARN', `No supported different-family reviewer found for implementer "${implementer}".`));
@@ -576,9 +604,9 @@ async function startReviewLoop(slug, opts = {}) {
         }
         const reason = !agents.includes(reviewer) ? 'blocked or unsupported' : 'launcher is not available';
         error(fmt.status('FAIL', `Unsupported reviewer: "${reviewer}" (${reason}) and no unblocked different-family fallback is available.`));
-        if (reviewerStatus.detail) error(`       Looked for: ${reviewerStatus.detail}`);
+        if (reviewerStatus.detail) {error(`       Looked for: ${reviewerStatus.detail}`);}
         error('\n' + fmt.status('INFO', 'Full runtime matrix:'));
-        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => error(`  ${line}`));
+        formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => error(`  ${line}`));
         error('\n' + fmt.status('FAIL', `No runnable reviewer route for implementer "${implementer}".`));
         exit(1);
         return;
@@ -641,7 +669,7 @@ async function startReviewLoop(slug, opts = {}) {
     if (state.phase === 'reviewing') {
       // Check if we can skip reviewer launch
       if (isContinue && attempt === initialRound) {
-        if (!dryRun) transitionTaskFn(slug, 'review', { rootDir: worktree, log });
+        if (!dryRun) {transitionTaskFn(slug, 'review', { rootDir: worktree, log });}
         if (forgejoEnabled) {
           log(fmt.status('INFO', `Round ${attempt}: checking for existing review by ${reviewer} since ${state.startedAt}...`));
           reviewState = await pollForReviewFn(prNumber, reviewer, state.startedAt, token, {
@@ -679,7 +707,7 @@ async function startReviewLoop(slug, opts = {}) {
           });
           if (!rebaseResult.ok) { exit(1); return; }
 
-          if (!dryRun) transitionTaskFn(slug, 'review', { rootDir: worktree, log });
+          if (!dryRun) {transitionTaskFn(slug, 'review', { rootDir: worktree, log });}
           state.phase = 'reviewing';
           writeReviewStateFn(slug, state, worktree);
           if (reviewer === 'autonomous' && !forgejoEnabled) {
@@ -691,11 +719,11 @@ async function startReviewLoop(slug, opts = {}) {
             try {
               reviewerLaunchResult = await startAgentFn('review', {
                 agent: reviewer,
-                prompt: (actualReviewer) => buildCompactReviewPromptFn({ reviewer, branch, implementer, focus, attempt, repoRoot: worktree, missionPath: effectiveMissionPath, actualReviewer }),
+                prompt: (/** @type {string} */ actualReviewer) => buildCompactReviewPromptFn({ reviewer, branch, implementer, focus, attempt, repoRoot: worktree, missionPath: effectiveMissionPath, actualReviewer }),
                 worktree, slug, role: 'reviewer', exclude: [implementer]
               });
-            } catch (err) {
-              error(fmt.status('FAIL', `Could not launch reviewer agent (${reviewer}): ${err.message}`));
+            } catch (/** @type {unknown} */ err) {
+              error(fmt.status('FAIL', `Could not launch reviewer agent (${reviewer}): ${/** @type {Error} */(err).message}`));
               exit(1); return;
             }
 
@@ -709,12 +737,12 @@ async function startReviewLoop(slug, opts = {}) {
             // The window is bounded to this round's launch so each round adds
             // only its own usage; accumulateStageStats sums the rounds into one
             // cumulative row per reviewer family.
-            const reviewSinceMs = stageLaunchSinceMs(reviewerLaunchResult && reviewerLaunchResult.result);
+            const reviewSinceMs = stageLaunchSinceMs((/** @type {{[key: string]: any}} */ (reviewerLaunchResult))?.result);
             recordStageStatsSafeFn('review', {
-              stage: 'review', slug, rootDir: worktree, worktree, reviewer, implementer,
-              result: reviewerLaunchResult && reviewerLaunchResult.result,
-              sinceMs: reviewSinceMs, log, error, state, writeReviewStateFn,
-              model: resolveAgentModel(reviewer, worktree),
+              stage: 'review', slug, rootDir: worktree, worktree, reviewer: /** @type {string} */ (reviewer), implementer,
+              result: (/** @type {{[key: string]: any}} */ (reviewerLaunchResult))?.result,
+              sinceMs: /** @type {number} */ (reviewSinceMs || 0), log, error, state, writeReviewStateFn,
+              model: resolveAgentModel(/** @type {string} */ (reviewer), /** @type {string} */ (worktree)),
             });
           }
 
@@ -744,22 +772,23 @@ async function startReviewLoop(slug, opts = {}) {
 
         if (isPollTimeout(reviewState)) {
           // Timeout recovery loop for reviewer
-          while (state.reviewerRetryCount < 2) {
-            state.reviewerRetryCount++;
+          const stateAny = /** @type {{[key: string]: any}} */ (state);
+          while ((stateAny['reviewerRetryCount'] || 0) < 2) {
+            stateAny['reviewerRetryCount'] = (stateAny['reviewerRetryCount'] || 0) + 1;
             writeReviewStateFn(slug, state, worktree);
-            const elapsedStr = formatElapsed(Date.now() - new Date(state.startedAt));
+const elapsedStr = formatElapsed(Date.now() - Date.parse(/** @type {string} */ (stateAny['startedAt'])));
             const recoveryPrompt = `RECOVERY: Reviewer timeout after ${elapsedStr}. Please complete the review for ${branch}.`;
-            log(fmt.status('INFO', `Round ${attempt}: relaunching reviewer (${reviewer}) with recovery prompt (retry ${state.reviewerRetryCount}/3)...`));
+            log(fmt.status('INFO', `Round ${attempt}: relaunching reviewer (${reviewer}) with recovery prompt (retry ${stateAny['reviewerRetryCount']}/3)...`));
 
             let relaunchResult;
             try {
               relaunchResult = await startAgentFn('review', {
                 agent: reviewer,
-                prompt: (actualReviewer) => buildCompactReviewPromptFn({ reviewer, branch, implementer, focus, attempt, repoRoot: worktree, missionPath: effectiveMissionPath, actualReviewer }) + '\n\n' + recoveryPrompt,
+                prompt: (/** @type {string} */ actualReviewer) => buildCompactReviewPromptFn({ reviewer, branch, implementer, focus, attempt, repoRoot: worktree, missionPath: effectiveMissionPath, actualReviewer }) + '\n\n' + recoveryPrompt,
                 worktree, slug, role: 'reviewer', exclude: [implementer]
               });
-            } catch (err) {
-              error(fmt.status('FAIL', `Could not relaunch reviewer agent (${reviewer}): ${err.message}`));
+            } catch (/** @type {unknown} */ err) {
+              error(fmt.status('FAIL', `Could not relaunch reviewer agent (${reviewer}): ${/** @type {Error} */(err).message}`));
               exit(1); return;
             }
 
@@ -791,7 +820,7 @@ async function startReviewLoop(slug, opts = {}) {
               });
             }
 
-            if (!isPollTimeout(reviewState)) break;
+            if (!isPollTimeout(reviewState)) {break;}
           }
 
           if (isPollTimeout(reviewState)) {
@@ -805,7 +834,7 @@ async function startReviewLoop(slug, opts = {}) {
         }
       }
 
-      if (dryRun) return;
+      if (dryRun) {return;}
 
       if (!reviewState) {
         error(fmt.status('FAIL', `Reviewer ${reviewer} did not submit a formal review outcome for ${branch}.`));
@@ -910,11 +939,11 @@ async function startReviewLoop(slug, opts = {}) {
         try {
           implementerLaunchResult = await startAgentFn('act-on-review', {
             agent: implementer,
-            prompt: (actualImplementer) => buildCompactActOnReviewPromptFn({ implementer, branch, attempt, reviewOutcome: reviewState, repoRoot: worktree, missionPath: effectiveMissionPath, actualImplementer }),
+            prompt: (/** @type {string} */ actualImplementer) => buildCompactActOnReviewPromptFn({ implementer, branch, attempt, reviewOutcome: reviewState, repoRoot: worktree, missionPath: effectiveMissionPath, actualImplementer }),
             worktree, slug, role: 'implementer', exclude: [reviewer]
           });
-        } catch (err) {
-          error(fmt.status('FAIL', `Could not launch implementer agent (${implementer}): ${err.message}`));
+        } catch (/** @type {unknown} */ err) {
+          error(fmt.status('FAIL', `Could not launch implementer agent (${implementer}): ${/** @type {Error} */(err).message}`));
           exit(1); return;
         }
 
@@ -927,12 +956,12 @@ async function startReviewLoop(slug, opts = {}) {
         // This is intentionally a separate stored phase from the initial
         // execute/active launch. The window is bounded to this round's launch
         // so each act-on-review round adds only its own usage.
-        const followUpSinceMs = stageLaunchSinceMs(implementerLaunchResult && implementerLaunchResult.result);
+        const followUpSinceMs = stageLaunchSinceMs((/** @type {{[key: string]: any}} */ (implementerLaunchResult))?.result);
         recordStageStatsSafeFn('active', {
           stage: 'follow-up', slug, rootDir: worktree, worktree, implementer, reviewer,
-          result: implementerLaunchResult && implementerLaunchResult.result,
-          sinceMs: followUpSinceMs, log, error, state, writeReviewStateFn,
-          model: resolveAgentModel(implementer, worktree),
+          result: (/** @type {{[key: string]: any}} */ (implementerLaunchResult))?.result,
+          sinceMs: /** @type {number} */ (followUpSinceMs || 0), log, error, state, writeReviewStateFn,
+          model: resolveAgentModel(/** @type {string} */ (implementer), /** @type {string} */ (worktree)),
         });
       }
 
@@ -960,22 +989,23 @@ async function startReviewLoop(slug, opts = {}) {
 
       if (isPollTimeout(disposition)) {
         // Timeout recovery loop for implementer
-        while (state.implementerRetryCount < 2) {
-          state.implementerRetryCount++;
+        const stateAny = /** @type {{[key: string]: any}} */ (state);
+        while ((stateAny['implementerRetryCount'] || 0) < 2) {
+          stateAny['implementerRetryCount'] = (stateAny['implementerRetryCount'] || 0) + 1;
           writeReviewStateFn(slug, state, worktree);
-          const elapsedStr = formatElapsed(Date.now() - new Date(state.startedAt));
-          const recoveryPrompt = `RECOVERY: Implementer disposition timeout after ${elapsedStr}. Please provide a disposition (PUSHBACK_ALL, BLOCKED, PARKED, or continue with fixes) for ${branch}.`;
-          log(fmt.status('INFO', `Round ${attempt}: relaunching implementer (${implementer}) with recovery prompt (retry ${state.implementerRetryCount}/3)...`));
+const elapsedStr = formatElapsed(Date.now() - Date.parse(/** @type {string} */ (stateAny['startedAt'])));
+            const recoveryPrompt = `RECOVERY: Implementer disposition timeout after ${elapsedStr}. Please provide a disposition (PUSHBACK_ALL, BLOCKED, PARKED, or continue with fixes) for ${branch}.`;
+          log(fmt.status('INFO', `Round ${attempt}: relaunching implementer (${implementer}) with recovery prompt (retry ${stateAny['implementerRetryCount']}/3)...`));
 
           let relaunchResult;
           try {
             relaunchResult = await startAgentFn('act-on-review', {
               agent: implementer,
-              prompt: (actualImplementer) => buildCompactActOnReviewPromptFn({ implementer, branch, attempt, reviewOutcome: reviewState, repoRoot: worktree, missionPath: effectiveMissionPath, actualImplementer }) + '\n\n' + recoveryPrompt,
+              prompt: (/** @type {string} */ actualImplementer) => buildCompactActOnReviewPromptFn({ implementer, branch, attempt, reviewOutcome: reviewState, repoRoot: worktree, missionPath: effectiveMissionPath, actualImplementer }) + '\n\n' + recoveryPrompt,
               worktree, slug, role: 'implementer', exclude: [reviewer]
             });
-          } catch (err) {
-            error(fmt.status('FAIL', `Could not relaunch implementer agent (${implementer}): ${err.message}`));
+          } catch (/** @type {unknown} */ err) {
+            error(fmt.status('FAIL', `Could not relaunch implementer agent (${implementer}): ${/** @type {Error} */(err).message}`));
             exit(1); return;
           }
 
@@ -1006,7 +1036,7 @@ async function startReviewLoop(slug, opts = {}) {
             });
           }
 
-          if (!isPollTimeout(disposition)) break;
+          if (!isPollTimeout(disposition)) {break;}
         }
 
         if (isPollTimeout(disposition)) {

package/lib/review/review-polling.js

@@ -13,6 +13,7 @@ const POLL_PROGRESS_EVERY_MS = 30_000;
 
 const POLL_TIMEOUT = Object.freeze({ __isPollTimeout: true });
 
+/** @param {number} ms */
 function delay(ms) {
   return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -20,29 +21,40 @@ function delay(ms) {
 function resolvePollIntervalMs() {
   const raw = process.env.AUTONOMOUS_REVIEW_POLL_INTERVAL_MS;
   const parsed = raw ? parseInt(raw, 10) : NaN;
-  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_POLL_INTERVAL_MS;
+  if (!Number.isFinite(parsed) || parsed <= 0) {return DEFAULT_POLL_INTERVAL_MS;}
   return parsed;
 }
 
+/** @param {number} [explicitSeconds] */
 function resolvePollTimeoutMs(explicitSeconds) {
-  if (Number.isFinite(explicitSeconds) && explicitSeconds > 0) {
+  if (typeof explicitSeconds === 'number' && Number.isFinite(explicitSeconds) && explicitSeconds > 0) {
     return explicitSeconds * 1000;
   }
   const raw = process.env.AUTONOMOUS_REVIEW_POLL_TIMEOUT_MS;
   const parsed = raw ? parseInt(raw, 10) : NaN;
-  if (!Number.isFinite(parsed) || parsed <= 0) return DEFAULT_POLL_MAX_WAIT_MS;
+  if (!Number.isFinite(parsed) || parsed <= 0) {return DEFAULT_POLL_MAX_WAIT_MS;}
   return parsed;
 }
 
+/** @param {number} startMs */
 function formatElapsed(startMs) {
   const secs = Math.round((Date.now() - startMs) / 1000);
   return `${secs}s`;
 }
 
+/** @param {*} result */
 function isPollTimeout(result) {
   return result === POLL_TIMEOUT;
 }
 
+/**
+ * @param {number} prNumber
+ * @param {string} reviewerUser
+ * @param {string} sinceIso
+ * @param {string} token
+ * @param {{getLatestReviewForPrFn?: Function, sleepFn?: Function, intervalMs?: number, timeoutMs?: number, verbose?: boolean, label?: string, retryCount?: number, log?: Function}} [options]
+ * @returns {Promise<string|typeof POLL_TIMEOUT|null>}
+ */
 async function pollForReview(prNumber, reviewerUser, sinceIso, token, options = {}) {
   const {
     getLatestReviewForPrFn = getLatestReviewForPr,
@@ -67,7 +79,7 @@ async function pollForReview(prNumber, reviewerUser, sinceIso, token, options =
   while (Date.now() < deadline) {
     const review = await getLatestReviewForPrFn(prNumber, reviewerUser, sinceIso, token);
     if (review) {
-      if (verbose) log(fmt.status('INFO', `${label}: reviewer state=${review.state} after ${formatElapsed(start)}.`));
+      if (verbose) {log(fmt.status('INFO', `${label}: reviewer state=${review.state} after ${formatElapsed(start)}.`));}
       return review.state;
     }
 
@@ -86,6 +98,14 @@ async function pollForReview(prNumber, reviewerUser, sinceIso, token, options =
   return POLL_TIMEOUT;
 }
 
+/**
+ * @param {number} prNumber
+ * @param {string} implementerUser
+ * @param {string} sinceIso
+ * @param {string} token
+ * @param {{getLatestDispositionForPrFn?: Function, sleepFn?: Function, intervalMs?: number, timeoutMs?: number, verbose?: boolean, label?: string, retryCount?: number, log?: Function}} [options]
+ * @returns {Promise<string|typeof POLL_TIMEOUT|null>}
+ */
 async function pollForDisposition(prNumber, implementerUser, sinceIso, token, options = {}) {
   const {
     getLatestDispositionForPrFn = getLatestDispositionForPr,
@@ -110,7 +130,7 @@ async function pollForDisposition(prNumber, implementerUser, sinceIso, token, op
   while (Date.now() < deadline) {
     const disposition = await getLatestDispositionForPrFn(prNumber, implementerUser, sinceIso, token);
     if (disposition) {
-      if (verbose) log(fmt.status('INFO', `${label}: disposition=${disposition} after ${formatElapsed(start)}.`));
+      if (verbose) {log(fmt.status('INFO', `${label}: disposition=${disposition} after ${formatElapsed(start)}.`));}
       return disposition;
     }