@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/review/review-commands.js

@@ -6,45 +6,50 @@
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 const fmt = require('../core/fmt');
-const { git, run, getCurrentBranch } = require('../core/git');
-const { findMissionDir, findMissionArea, resolveWorktree, inferSlug, updateGraphifyKnowledgeGraph, findCheckpoints, isMissionArtifact, isWorkflowGeneratedArtifact, missionBranchName, missionBaseDir } = require('../core/mission-utils');
-const { resolveTaskFile, getTaskStatus, getAcceptanceCriteria, setTaskStatus, setTaskAssignee, enforceTaskAssignee, getTaskAssignee, getTaskImplementer, reportTaskResolution, transitionTask } = require('../tools/backlog');
+const { run, getCurrentBranch } = require('../core/git');
+const { findMissionDir, findMissionArea, resolveWorktree, inferSlug, findCheckpoints, missionBranchName, missionBaseDir } = require('../core/mission-utils');
+const { resolveTaskFile, getTaskStatus, getAcceptanceCriteria, getTaskAssignee, getTaskImplementer, reportTaskResolution, transitionTask } = require('../tools/backlog');
 const { toVirtual } = require('../core/state-map');
-const { getPrStatus, readToken, getLatestReviewForPr, getLatestDispositionForPr, postComment, postReview, createPr, providerAvailable, getComments, closePr, resolveReviewUser, isProviderEnabled } = require('./review-adapter');
+const { getPrStatus, readToken, postComment, createPr, getComments, closePr, resolveReviewUser, isProviderEnabled } = require('./review-adapter');
 const { buildAutonomousReviewMatrix, formatMatrixSummary } = require('../core/runtime-matrix');
-const { buildCompactReviewPrompt, buildCompactActOnReviewPrompt, buildReviewPrompt, buildActOnReviewPrompt } = require('./review-prompts');
-const { ReviewState, readReviewState, writeReviewState, resetReviewState, VALID_PHASES, resolveReviewIdentity } = require('./review-state');
-const { createEvent, importLegacyArtifact, importAllLegacyArtifacts, consumeHumanNotes,
-        VALID_EVENT_TYPES, ALL_EVENT_TYPES, LEGACY_ARTIFACT_TO_EVENT_TYPE,
+
+const { readReviewState, writeReviewState, resolveReviewIdentity } = require('./review-state');
+const { createEvent, importAllLegacyArtifacts, ALL_EVENT_TYPES,
         isValidEventType, shouldMirrorToProvider, readAllEvents } = require('./review-events');
-const { assertAgentSupported, workflowLauncherStatus, startAgent, eligibleAgentsForStep, selectAgent } = require('../agents/agents');
+const { startAgent } = require('../agents/agents');
 const { performHandoff } = require('../commands/handoff');
 const { formatVerificationCommand, runVerificationGate } = require('../core/verification');
 const { bootstrapReviewSurface } = require('../tools/setup-review');
 const { resolveReviewAdapter } = require('../core/product-config');
 
-// Import from review-polling module
-const { POLL_TIMEOUT, delay, resolvePollIntervalMs, resolvePollTimeoutMs, formatElapsed, isPollTimeout, pollForReview, pollForDisposition } = require('./review-polling');
 // Import from review-artifacts module
-const { buildMetadataFooter, reviewArtifactPath, readArtifactFile, deleteArtifactFile, normalizeReviewVerdict, normalizeDisposition, postWorkflowComment, postWorkflowReview, consumeReviewerArtifacts, consumeImplementerArtifacts } = require('./review-artifacts');
+const { buildMetadataFooter, reviewArtifactPath, postWorkflowComment, postWorkflowReview, consumeReviewerArtifacts } = require('./review-artifacts');
 
 const DEFAULT_MAX_ATTEMPTS = 5;
-const CONTINUE_SKIP_CHECK_TIMEOUT_MS = 10_000;
-const SHARED_FILE_REBASE_CONFLICT_RE = /shared file(?:\(s\))? require agent-assisted resolution|shared-file-conflicts/i;
 
 // ============================================================================
 // Internal Helpers
 // ============================================================================
 
+/** @param {string[]} args @param {string} flag */
 function flagValue(args, flag) {
   const idx = args.indexOf(flag);
-  if (idx === -1) return null;
+  if (idx === -1) {return null;}
   const val = args[idx + 1];
-  if (!val || val.startsWith('--')) return null;
+  if (!val || val.startsWith('--')) {return null;}
   return val;
 }
 
+/**
+ * @param {string[]} args
+ * @param {string} inlineFlag
+ * @param {string} fileFlag
+ * @param {string} label
+ * @param {{readFileSync?: Function, error?: Function, exit?: Function}} [options]
+ * @returns {string|null}
+ */
 function readTextFlag(args, inlineFlag, fileFlag, label, options = {}) {
   const readFileSync = options.readFileSync || fs.readFileSync;
   const error = options.error || fmt.log.plainError;
@@ -54,7 +59,7 @@ function readTextFlag(args, inlineFlag, fileFlag, label, options = {}) {
     try {
       return readFileSync(filePath, 'utf8').trimEnd();
     } catch (err) {
-      error(`Could not read ${label} from ${fmt.path(filePath)}: ${err.message}`);
+      error(`Could not read ${label} from ${fmt.path(filePath)}: ${/** @type {Error} */(err).message}`);
       exit(1);
       return null;
     }
@@ -63,6 +68,7 @@ function readTextFlag(args, inlineFlag, fileFlag, label, options = {}) {
   return flagValue(args, inlineFlag);
 }
 
+/** @param {string[]} findings */
 function formatStaticReviewFindings(findings) {
   const lines = [
     'Static review found the following issue(s) before autonomous review:',
@@ -75,6 +81,7 @@ function formatStaticReviewFindings(findings) {
   return lines.join('\n');
 }
 
+/** @param {string} slug */
 function formatStaticReviewSuccess(slug) {
   return [
     `Static review for ${slug} found zero issues.`,
@@ -88,6 +95,11 @@ function formatStaticReviewSuccess(slug) {
   ].join('\n');
 }
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, error?: Function, getTaskStatusFn?: Function, resolveTaskFileFn?: Function, transitionTaskFn?: Function, rootDir?: string}} [options]
+ * @returns {{repaired: boolean, skipped?: boolean, currentStatus?: string}}
+ */
 function repairStaleActiveTaskAfterReview(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -114,6 +126,11 @@ function repairStaleActiveTaskAfterReview(slug, options = {}) {
   return { repaired: true, currentStatus };
 }
 
+/**
+ * @param {string} slug
+ * @param {{worktree?: string, taskFile?: string|null, log?: Function, error?: Function}} options
+ * @returns {Promise<{ok: boolean, dirty?: boolean, unsafe?: boolean}>}
+ */
 async function commitPersistedReviewOutputs(slug, options = {}) {
   const { commitSafeMissionArtifacts } = require('./review-loop');
   return commitSafeMissionArtifacts(slug, options.worktree || process.cwd(), {
@@ -123,6 +140,12 @@ async function commitPersistedReviewOutputs(slug, options = {}) {
   });
 }
 
+/**
+ * @param {string} slug
+ * @param {string} message
+ * @param {{log?: Function, error?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, resolveWorktreeFn?: Function, readTokenFn?: Function, postCommentFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, readReviewStateFn?: Function, buildMetadataFooterFn?: Function, rootDir?: string}} [options]
+ * @returns {{ok: boolean, error?: string}}
+ */
 function postStaticReviewComment(slug, message, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -181,9 +204,13 @@ function postStaticReviewComment(slug, message, options = {}) {
  * Inspects git diff for changed files, checks the final checkpoint for
  * a Goal Check table, and returns findings.
  */
+/**
+ * @param {string} slug
+ * @param {{log?: Function, findMissionDir?: Function, findCheckpoints?: Function, readFileSync?: Function, run?: Function, resolveWorktree?: Function, missionPath?: string, rootDir?: string}} [options]
+ * @returns {{ok: boolean, findings: string[]}}
+ */
 function performStaticReview(slug, options = {}) {
   const log = options.log || fmt.log.plain;
-  const error = options.error || fmt.log.plainError;
   const findMissionDirFn = options.findMissionDir || findMissionDir;
   const findCheckpointsFn = options.findCheckpoints || findCheckpoints;
   const readFileSyncFn = options.readFileSync || fs.readFileSync;
@@ -233,12 +260,12 @@ function performStaticReview(slug, options = {}) {
       let pastHeader = false;
       for (const line of linesAfterHeader) {
         const trimmed = line.trim();
-        if (trimmed === '') continue;
+        if (trimmed === '') {continue;}
         if (!pastHeader && headerPattern.test(trimmed)) {
           pastHeader = true;
           continue;
         }
-        if (separatorPattern.test(trimmed)) continue;
+        if (separatorPattern.test(trimmed)) {continue;}
         if (pastHeader && evidenceLinePattern.test(trimmed)) {
           foundEvidence = true;
           break;
@@ -252,14 +279,14 @@ function performStaticReview(slug, options = {}) {
       }
     }
   } catch (err) {
-    findings.push(`Could not read final checkpoint ${path.basename(finalCheckpoint)}: ${err.message}`);
+    findings.push(`Could not read final checkpoint ${path.basename(finalCheckpoint)}: ${/** @type {Error} */(err).message}`);
   }
 
   // Inspect git diff for changed files
   const baseBranch = require('../core/mission-utils').getPrimaryBranch(rootDir);
   const diffResult = runFn('git', ['diff', `${baseBranch}..HEAD`, '--name-only'], { cwd: rootDir });
   if (diffResult.status === 0 && diffResult.stdout) {
-    const changedFiles = diffResult.stdout.trim().split('\n').filter(f => f.trim());
+    const changedFiles = diffResult.stdout.trim().split('\n').filter((/** @type {string} */ f) => f.trim());
     const missionDirPrefix = path.relative(rootDir, missionBaseDir(rootDir)).split(path.sep).join('/') + '/';
     log(`Changed files in branch: ${changedFiles.join(', ')}`);
     // Check for unexpected areas — missions may legitimately touch many surfaces.
@@ -270,11 +297,11 @@ function performStaticReview(slug, options = {}) {
       '.agents/', '.github/', '.vscode/', '.graphifyignore',
     ];
     const knownExtensions = ['.sh', '.csv', '.json', '.yaml', '.yml', '.toml', '.lock', '.cfg', '.ini', '.env', '.txt', '.properties', '.sql', '.css', '.html', '.xml', '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.pdf', '.tar', '.gz', '.zip'];
-    const unexpectedFiles = changedFiles.filter(f =>
-      !knownAreas.some(area => f.startsWith(area)) &&
+      const unexpectedFiles = changedFiles.filter((/** @type {string} */ f) =>
+      !knownAreas.some((/** @type {string} */ area) => f.startsWith(area)) &&
       !f.startsWith(missionDirPrefix) &&
       !f.endsWith('.md') &&
-      !knownExtensions.some(ext => f.toLowerCase().endsWith(ext))
+      !knownExtensions.some((/** @type {string} */ ext) => f.toLowerCase().endsWith(ext))
     );
     if (unexpectedFiles.length > 0) {
       log(fmt.status('WARN', `Changed files outside known areas (may be intentional): ${unexpectedFiles.join(', ')}`));
@@ -292,6 +319,12 @@ function performStaticReview(slug, options = {}) {
 // Command: verifyReview
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {boolean|string} skipGate
+ * @param {{log?: Function, error?: Function, exit?: Function, resolveWorktreeFn?: Function, findMissionDirFn?: Function, getCurrentBranchFn?: Function, resolveTaskFileFn?: Function, getPrStatusFn?: Function, getTaskStatusFn?: Function, toVirtualFn?: Function, findMissionAreaFn?: Function, runFn?: Function, getAcceptanceCriteriaFn?: Function, formatMatrixSummaryFn?: Function, buildAutonomousReviewMatrixFn?: Function, readReviewStateFn?: Function, isReviewProviderEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, cwdFn?: Function, missionPath?: string, skipGate?: boolean}} [options]
+ * @returns {void}
+ */
 function verifyReview(slug, skipGate, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -419,12 +452,12 @@ function verifyReview(slug, skipGate, options = {}) {
     if (acceptanceCriteria.length === 0) {
       log('  - No Acceptance Criteria found on the Backlog task.');
     } else {
-      acceptanceCriteria.forEach(line => log(`  ${line}`));
+      acceptanceCriteria.forEach((/** @type {string} */ line) => log(`  ${line}`));
     }
   }
 
   log(fmt.status('INFO', 'Autonomous review runtime matrix:'));
-  formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach(line => log(line));
+    formatMatrixSummaryFn(buildAutonomousReviewMatrixFn()).forEach((/** @type {string} */ line) => log(line));
 
   // Show persisted reviewer state if present
   const persisted = readReviewStateFn(slug);
@@ -449,13 +482,18 @@ function verifyReview(slug, skipGate, options = {}) {
 // Command: submitForReview
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {boolean|string} skipGate
+ * @param {{exit?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, resolveWorktreeFn?: Function, performHandoffFn?: Function, readReviewStateFn?: Function, isReviewProviderEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, log?: Function}} [options]
+ * @returns {Promise<void>}
+ */
 async function submitForReview(slug, skipGate, options = {}) {
   const exit = options.exit || process.exit;
   const resolveTaskFileFn = options.resolveTaskFileFn || resolveTaskFile;
   const getTaskImplementerFn = options.getTaskImplementerFn || getTaskImplementer;
   const resolveWorktreeFn = options.resolveWorktreeFn || resolveWorktree;
   const performHandoffFn = options.performHandoffFn || performHandoff;
-  const resolveReviewUserFn = options.resolveReviewUserFn || options.resolveForgejoUserFn || resolveReviewUser;
   const readReviewStateFn = options.readReviewStateFn || readReviewState;
   const isReviewProviderEnabledFn = options.isReviewProviderEnabledFn || options.isForgejoReviewEnabledFn || isProviderEnabled;
   const log = options.log || fmt.log.plain;
@@ -498,6 +536,11 @@ async function submitForReview(slug, skipGate, options = {}) {
 // Command: readComments
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, error?: Function, exit?: Function, readTokenFn?: Function, readReviewStateFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, getCommentsFn?: Function, readAllEventsFn?: Function, isReviewProviderEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, worktree?: string}} [options]
+ * @returns {Promise<void>}
+ */
 async function readComments(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -522,7 +565,7 @@ async function readComments(slug, options = {}) {
     }
     for (const e of events) {
       let label = e.event_type || 'event';
-      if (e.round != null) label += ` round ${e.round}`;
+      if (e.round !== null) {label += ` round ${e.round}`;}
       log(`--- ${label} | ${e.actor || 'unknown'} (${e.timestamp || e.fileCreated || ''}) ---`);
       log(e.content || '(no body)');
       log('');
@@ -564,7 +607,7 @@ async function readComments(slug, options = {}) {
 
   for (const c of comments) {
     let label = c.kind;
-    if (c.location) label += ` ${c.location}`;
+    if (c.location) {label += ` ${c.location}`;}
     log(`--- ${label} | ${c.user} (${c.created}) ---`);
     log(c.body || '(no body)');
     log('');
@@ -575,6 +618,11 @@ async function readComments(slug, options = {}) {
 // Command: pushRound
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, error?: Function, exit?: Function, resolveWorktreeFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, transitionTaskFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, isReviewProviderEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, readTokenFn?: Function, readReviewStateFn?: Function, createPrFn?: Function, bootstrapReviewSurfaceFn?: Function, resolveReviewAdapterFn?: Function, cwdFn?: Function, force?: boolean}} [options]
+ * @returns {Promise<void>}
+ */
 async function pushRound(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -677,6 +725,11 @@ async function pushRound(slug, options = {}) {
 // Command: showReviewStatus
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, readReviewStateFn?: Function, resolveWorktreeFn?: Function}} [options]
+ * @returns {void}
+ */
 function showReviewStatus(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const readReviewStateFn = options.readReviewStateFn || readReviewState;
@@ -712,6 +765,12 @@ function showReviewStatus(slug, options = {}) {
 // Command: commentRound
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} message
+ * @param {{log?: Function, error?: Function, exit?: Function, readReviewStateFn?: Function, writeReviewStateFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, rootDir?: string, readTokenFn?: Function, postCommentFn?: Function, buildMetadataFooterFn?: Function}} [options]
+ * @returns {void}
+ */
 function commentRound(slug, message, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -733,7 +792,7 @@ function commentRound(slug, message, options = {}) {
   reviewIdentity = resolveReviewUserFn(reviewIdentity);
   const result = postWorkflowComment(slug, message, {
     rootDir,
-    reviewIdentity,
+    reviewIdentity: reviewIdentity || undefined,
     readTokenFn: options.readTokenFn,
     postCommentFn: options.postCommentFn,
     buildMetadataFooterFn: options.buildMetadataFooterFn,
@@ -756,10 +815,14 @@ function commentRound(slug, message, options = {}) {
 // Command: consumeArtifacts
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, error?: Function, resolveWorktreeFn?: Function, transitionTaskFn?: Function, consumeReviewerArtifactsFn?: Function, resolveTaskFileFn?: Function, getTaskAssigneeFn?: Function, getTaskStatusFn?: Function, resolveArtifactDirFn?: Function, readReviewStateFn?: Function, createEventFn?: Function, readArtifactFn?: Function, deleteArtifactFn?: Function}} [options]
+ * @returns {Promise<{ok: boolean, consumed: boolean, reviewState?: string|null}>}
+ */
 async function consumeArtifacts(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
-  const exit = options.exit || process.exit;
   const resolveWorktreeFn = options.resolveWorktreeFn || resolveWorktree;
   const transitionTaskFn = options.transitionTaskFn || transitionTask;
   const consumeReviewerArtifactsFn = options.consumeReviewerArtifactsFn || consumeReviewerArtifacts;
@@ -853,6 +916,13 @@ async function consumeArtifacts(slug, options = {}) {
 // Command: submitReviewRound
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string} outcome
+ * @param {string} message
+ * @param {{log?: Function, error?: Function, exit?: Function, transitionTaskFn?: Function, readReviewStateFn?: Function, writeReviewStateFn?: Function, isReviewProviderEnabledFn?: Function, isForgejoReviewEnabledFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, resolveTaskFileFn?: Function, getTaskStatusFn?: Function, worktree?: string, readTokenFn?: Function, postReviewFn?: Function, getPrAuthorFn?: Function, createEventFn?: Function, buildMetadataFooterFn?: Function}} [options]
+ * @returns {void}
+ */
 function submitReviewRound(slug, outcome, message, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -910,7 +980,7 @@ function submitReviewRound(slug, outcome, message, options = {}) {
       'request-changes': 'review',
       'comment': 'review'
     };
-    const backlogStatus = backlogStatusMap[outcome];
+    const backlogStatus = backlogStatusMap[/** @type {keyof typeof backlogStatusMap} */ (outcome)];
     if (backlogStatus && !transitionTaskFn(slug, backlogStatus, { rootDir: worktree, log })) {
       log(fmt.status('WARN', `Could not transition backlog task ${slug} to ${backlogStatus}.`));
     }
@@ -932,7 +1002,7 @@ function submitReviewRound(slug, outcome, message, options = {}) {
   reviewIdentity = resolveReviewUserFn(reviewIdentity);
   const result = postWorkflowReview(slug, outcome, message, {
     worktree,
-    reviewIdentity,
+    reviewIdentity: reviewIdentity || undefined,
     readTokenFn: options.readTokenFn,
     postReviewFn: options.postReviewFn,
     getPrAuthorFn: options.getPrAuthorFn,
@@ -996,6 +1066,11 @@ function submitReviewRound(slug, outcome, message, options = {}) {
 // Command: closeMissionPr
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {{log?: Function, error?: Function, exit?: Function, readTokenFn?: Function, readReviewStateFn?: Function, resolveReviewUserFn?: Function, resolveForgejoUserFn?: Function, closePrFn?: Function, worktree?: string}} [options]
+ * @returns {Promise<void>}
+ */
 async function closeMissionPr(slug, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -1037,6 +1112,12 @@ async function closeMissionPr(slug, options = {}) {
 // Event CLI Handlers
 // ============================================================================
 
+/**
+ * @param {string} slug
+ * @param {string[]} args
+ * @param {{log?: Function, error?: Function, exit?: Function, resolveWorktreeFn?: Function, readReviewStateFn?: Function}} [options]
+ * @returns {void}
+ */
 function createEventHandler(slug, args, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -1071,14 +1152,14 @@ function createEventHandler(slug, args, options = {}) {
       content = fs.readFileSync(inputFile, 'utf8');
       log(fmt.status('INFO', `Read event content from: ${inputFile}`));
     } catch (err) {
-      error(fmt.status('FAIL', `Failed to read input file: ${err.message}`));
+      error(fmt.status('FAIL', `Failed to read input file: ${/** @type {Error} */(err).message}`));
       exit(1);
       return;
     }
   }
 
   const round = roundRaw ? parseInt(roundRaw, 10) : undefined;
-  if (roundRaw && isNaN(round)) {
+  if (roundRaw && (isNaN(/** @type {number} */ (round))) ) {
     error(fmt.status('FAIL', `--round must be a number, got "${roundRaw}"`));
     exit(1);
     return;
@@ -1087,12 +1168,13 @@ function createEventHandler(slug, args, options = {}) {
   const worktree = resolveWorktreeFn(slug) || process.cwd();
 
   // Build params
+  /** @type {{content: string, round?: number, phase?: string, actor?: string, disposition?: string, verdict?: string, fixedItems?: string[], pushedBackItems?: string[], parkedItems?: string[], blockedReason?: string}} */
   const params = { content };
-  if (round !== undefined) params.round = round;
-  if (phase) params.phase = phase;
-  if (actor) params.actor = actor;
-  if (disposition) params.disposition = disposition;
-  if (verdict) params.verdict = verdict;
+  if (round !== undefined) {params.round = round;}
+  if (phase) {params.phase = phase;}
+  if (actor) {params.actor = actor;}
+  if (disposition) {params.disposition = disposition;}
+  if (verdict) {params.verdict = verdict;}
 
   const readReviewStateFn = options.readReviewStateFn || readReviewState;
   const { identityUser: stateReviewIdentity } = resolveReviewIdentity(slug, worktree, {
@@ -1152,6 +1234,12 @@ function createEventHandler(slug, args, options = {}) {
   log(fmt.status('PASS', `Created review event at: ${result.path}`));
 }
 
+/**
+ * @param {string} slug
+ * @param {string[]} args
+ * @param {{log?: Function, error?: Function, exit?: Function, resolveWorktreeFn?: Function}} [options]
+ * @returns {void}
+ */
 function importLegacyHandler(slug, args, options = {}) {
   const log = options.log || fmt.log.plain;
   const error = options.error || fmt.log.plainError;
@@ -1161,21 +1249,27 @@ function importLegacyHandler(slug, args, options = {}) {
   const tmpDir = flagValue(args, '--tmp-dir') || process.env.WORKFLOW_TMP_DIR || os.tmpdir();
   const worktree = resolveWorktreeFn(slug) || process.cwd();
 
-  const result = importAllLegacyArtifacts(slug, tmpDir, { worktree, log, error });
+  const result = importAllLegacyArtifacts(slug, { tmpDir, worktree, log, error });
   
+  const errors = result.errors || [];
   if (!result.ok) {
-    error(fmt.status('FAIL', `Legacy import failed: ${result.error}`));
+    error(fmt.status('FAIL', `Legacy import failed: ${errors.join(', ')}`));
     exit(1);
     return;
   }
 
-  log(fmt.status('PASS', `Imported ${result.imported} legacy artifacts for ${slug}`));
+  log(fmt.status('PASS', `Imported ${result.imported ? result.imported.length : 0} legacy artifacts for ${slug}`));
 }
 
 // ============================================================================
 // Main Dispatcher
 // ============================================================================
 
+/**
+ * @param {string[]} args
+ * @param {{inferSlugFn?: Function, log?: Function, error?: Function, exit?: Function, verifyReviewFn?: Function, submitForReviewFn?: Function, consumeArtifactsFn?: Function, pushRoundFn?: Function, readCommentsFn?: Function, commentRoundFn?: Function, submitReviewRoundFn?: Function, closeMissionPrFn?: Function, startReviewLoopFn?: Function, recordStageStatsSafeFn?: Function, startAgentFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, getPrStatusFn?: Function, readReviewStateFn?: Function, performStaticReviewFn?: Function, postStaticReviewCommentFn?: Function, resolveWorktreeFn?: Function, run?: Function, missionPath?: string}} [options]
+ * @returns {Promise<void>}
+ */
 async function review(args, options = {}) {
   const inferSlugFn = options.inferSlugFn || inferSlug;
   const log = options.log || fmt.log.plain;
@@ -1322,7 +1416,7 @@ const recordStageStatsSafeFn = options.recordStageStatsSafeFn || require('./revi
           log(fmt.status('WARN', `Static review found ${staticResult.findings.length} finding(s) but the implementer could not be resolved for ${fmt.slug(slug)} — not re-launching the implementer and not starting the review loop.`));
         } else {
           log(`\nStatic review found ${staticResult.findings.length} finding(s). Re-launching implementer (${fmt.agent(implementer)}) with a targeted fix prompt...`);
-          const findingLines = staticResult.findings.map(f => `- ${f}`).join('\n');
+          const findingLines = staticResult.findings.map((/** @type {string} */ f) => `- ${f}`).join('\n');
           const prompt = `Static review of your mission branch found the following issue(s). Fix them and commit, then stop:\n${findingLines}`;
           await startAgentFn('active', { prompt, worktree: worktreeForStatic, agent: implementer, slug });
         }