@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/commands/mission-start.js

@@ -11,36 +11,37 @@ const { getPrStatus } = require('../tools/forgejo');
 const { isForgejoReviewEnabled } = require('../core/product-config');
 const stats = require('./stats');
 
-function missionStart(args, options = {}) {
-  const log = options.log || fmt.log.plain;
-  const error = options.error || fmt.log.plainError;
-  const cwdFn = options.cwdFn || (() => process.cwd());
-  const getCurrentBranchFn = options.getCurrentBranchFn || getCurrentBranch;
-  const resolveTaskFileFn = options.resolveTaskFileFn || resolveTaskFile;
-  const getTaskStatusFn = options.getTaskStatusFn || getTaskStatus;
-  const toVirtualFn = options.toVirtualFn || toVirtual;
-  const findMissionDirFn = options.findMissionDirFn || findMissionDir;
-  const findCheckpointsFn = options.findCheckpointsFn || findCheckpoints;
-  const getFirstLineFn = options.getFirstLineFn || getFirstLine;
-  const inferSlugFn = options.inferSlugFn || inferSlug;
-  const getMissionYearFn = options.getMissionYearFn || getMissionYear;
-  const conventionalWorktreePathFn = options.conventionalWorktreePathFn || conventionalWorktreePath;
-  const getLastCommitFn = options.getLastCommitFn || getLastCommit;
-  const getPrStatusFn = options.getPrStatusFn || getPrStatus;
-  const evaluateRepositoryReadinessFn = options.evaluateRepositoryReadinessFn || evaluateRepositoryReadiness;
-  const evaluateReviewSetupFn = options.evaluateReviewSetupFn || evaluateReviewSetup;
-  const adapterChecklistFn = options.adapterChecklistFn || adapterChecklist;
-  const resolveMissionClassificationFn = options.resolveMissionClassificationFn || stats.resolveMissionClassification;
-  const isForgejoReviewEnabledFn = options.isForgejoReviewEnabledFn || isForgejoReviewEnabled;
-  const fsExistsSync = options.fsExistsSync || fs.existsSync;
-  const resolveMissionBaseBranchFn = options.resolveMissionBaseBranchFn || resolveMissionBaseBranch;
-  const getPrimaryBranchFn = options.getPrimaryBranchFn || getPrimaryBranch;
-  const runFn = options.gitFn || git;
+/** @param {string[]} args @param {{log?: Function, error?: Function, cwdFn?: Function, getCurrentBranchFn?: Function, resolveTaskFileFn?: Function, getTaskStatusFn?: Function, toVirtualFn?: Function, findMissionDirFn?: Function, findCheckpointsFn?: Function, getFirstLineFn?: Function, inferSlugFn?: Function, getMissionYearFn?: Function, conventionalWorktreePathFn?: Function, getLastCommitFn?: Function, getPrStatusFn?: Function, evaluateRepositoryReadinessFn?: Function, evaluateReviewSetupFn?: Function, adapterChecklistFn?: Function, resolveMissionClassificationFn?: Function, isForgejoReviewEnabledFn?: Function, fsExistsSync?: Function, resolveMissionBaseBranchFn?: Function, getPrimaryBranchFn?: Function, gitFn?: Function, command?: string, returnResult?: boolean}} opts */
+function missionStart(args, opts = {}) {
+  const log = opts.log || fmt.log.plain;
+  const error = opts.error || fmt.log.plainError;
+  const cwdFn = opts.cwdFn || (() => process.cwd());
+  const getCurrentBranchFn = opts.getCurrentBranchFn || getCurrentBranch;
+  const resolveTaskFileFn = opts.resolveTaskFileFn || resolveTaskFile;
+  const getTaskStatusFn = opts.getTaskStatusFn || getTaskStatus;
+  const toVirtualFn = opts.toVirtualFn || toVirtual;
+  const findMissionDirFn = opts.findMissionDirFn || findMissionDir;
+  const findCheckpointsFn = opts.findCheckpointsFn || findCheckpoints;
+  const getFirstLineFn = opts.getFirstLineFn || getFirstLine;
+  const inferSlugFn = opts.inferSlugFn || inferSlug;
+  const getMissionYearFn = opts.getMissionYearFn || getMissionYear;
+  const conventionalWorktreePathFn = opts.conventionalWorktreePathFn || conventionalWorktreePath;
+  const getLastCommitFn = opts.getLastCommitFn || getLastCommit;
+  const getPrStatusFn = opts.getPrStatusFn || getPrStatus;
+  const evaluateRepositoryReadinessFn = opts.evaluateRepositoryReadinessFn || evaluateRepositoryReadiness;
+  const evaluateReviewSetupFn = opts.evaluateReviewSetupFn || evaluateReviewSetup;
+  const adapterChecklistFn = opts.adapterChecklistFn || adapterChecklist;
+  const resolveMissionClassificationFn = opts.resolveMissionClassificationFn || stats.resolveMissionClassification;
+  const isForgejoReviewEnabledFn = opts.isForgejoReviewEnabledFn || isForgejoReviewEnabled;
+  const fsExistsSync = opts.fsExistsSync || fs.existsSync;
+  const resolveMissionBaseBranchFn = opts.resolveMissionBaseBranchFn || resolveMissionBaseBranch;
+  const getPrimaryBranchFn = opts.getPrimaryBranchFn || getPrimaryBranch;
+  const runFn = opts.gitFn || git;
 
   const explicitSlug = args[0];
   const slug = inferSlugFn(explicitSlug);
-  const isVerifyOnly = options.command === 'verify-env' || !slug;
-  const returnResult = Boolean(options.returnResult);
+  const isVerifyOnly = opts.command === 'verify-env' || !slug;
+  const returnResult = Boolean(opts.returnResult);
 
   if (isVerifyOnly) {
     log(fmt.status('INFO', 'Running environment diagnostics (verify-env)...'));
@@ -49,6 +50,7 @@ function missionStart(args, options = {}) {
   }
 
   let overallFail = false;
+  /** @type{string[]} */
   const remediationSteps = [];
 
   // Check 1: PWD
@@ -150,8 +152,8 @@ function missionStart(args, options = {}) {
         } else {
           log(fmt.status('PASS', `Backlog classification: ${classification}`));
         }
-      } catch (error) {
-        log(fmt.status('FAIL', `Backlog classification: ${error.message}`));
+      } catch (/** @type {unknown} */ error) {
+        log(fmt.status('FAIL', `Backlog classification: ${/** @type {any} */(error).message}`));
         overallFail = true;
       }
     } else {
@@ -229,10 +231,13 @@ function missionStart(args, options = {}) {
 }
 
 // Extracted so callers can test the returnResult path without live git dependencies.
+/** @param {boolean} overallFail @param {boolean} returnResult @param {{error?: Function, log?: Function, remediationSteps?: string[]}} options */
 function completePreflightOrExit(overallFail, returnResult, options = {}) {
-  const error = options.error || fmt.log.plainError;
-  const log = options.log || fmt.log.plain;
-  const remediationSteps = options.remediationSteps || [];
+  /** @type{{error?: Function, log?: Function, remediationSteps?: string[]}} */
+  const opts = options;
+  const error = opts.error || fmt.log.plainError;
+  const log = opts.log || fmt.log.plain;
+  const remediationSteps = opts.remediationSteps || [];
   if (overallFail) {
     let msg = '\n' + fmt.status('FAIL', 'Environment verdict: NOT USABLE');
     if (remediationSteps.length > 0) {
@@ -244,11 +249,11 @@ function completePreflightOrExit(overallFail, returnResult, options = {}) {
       msg += ' — fix blockers above before proceeding.';
     }
     error(msg);
-    if (returnResult) return { pass: false };
+    if (returnResult) {return { pass: false };}
     process.exit(1);
   } else {
     log('\n' + fmt.status('PASS', 'Environment verdict: USABLE — this repository is ready for workflow commands.'));
-    if (returnResult) return { pass: true };
+    if (returnResult) {return { pass: true };}
     process.exit(0);
   }
 }

package/lib/commands/rebase.js

@@ -1,9 +1,9 @@
 const path = require('path');
 const { detectRebaseState, git, getCurrentBranch } = require('../core/git');
 const { resolveConflictsForMission } = require('./integrate');
-const { findMissionDir, findMissionArea, inferSlug, resolveWorktree, conventionalWorktreePath, getPrimaryWorktree, getPrimaryBranch, resolveMissionBaseBranch, missionBranchName, missionDirForSlug, getMissionYear } = require('../core/mission-utils');
+const { findMissionDir, findMissionArea, inferSlug, resolveWorktree, conventionalWorktreePath, getPrimaryWorktree, getPrimaryBranch, resolveMissionBaseBranch, missionBranchName, missionDirForSlug } = require('../core/mission-utils');
 const { startAgent } = require('../agents/agents');
-  const { createPr, readToken, resolveForgejoUser } = require('../tools/forgejo');
+  const { createPr, readToken, resolveForgejoUser, fetchReviewBranch } = require('../tools/forgejo');
 const { resolveTaskFile, getTaskImplementer } = require('../tools/backlog');
 const { resolveReviewIdentity } = require('../review/review-state');
 const { isForgejoReviewEnabled } = require('../core/product-config');
@@ -16,6 +16,7 @@ const { formatVerificationCommand } = require('../core/verification');
  *
  * Usage: px rebase [<slug>] [--push]
  */
+/** @param {string[]} args @param {{inferSlugFn?: Function, findMissionDirFn?: Function, findMissionAreaFn?: Function, getCurrentBranchFn?: Function, resolveConflictsFn?: Function, startAgentFn?: Function, createPrFn?: Function, readTokenFn?: Function, resolveForgejoUserFn?: Function, resolveTaskFileFn?: Function, getTaskImplementerFn?: Function, detectRebaseStateFn?: Function, resolveMissionBaseBranchFn?: Function, gitFn?: Function, exitFn?: Function, isForgejoReviewEnabledFn?: Function, fetchReviewBranchFn?: Function}} opts */
 async function rebase(args, {
   inferSlugFn = inferSlug,
   findMissionDirFn = findMissionDir,
@@ -31,8 +32,9 @@ async function rebase(args, {
   detectRebaseStateFn = detectRebaseState,
   resolveMissionBaseBranchFn = resolveMissionBaseBranch,
   gitFn = git,
-  exitFn = (code) => process.exit(code),
+  exitFn = (/** @type{number} */ code) => process.exit(code),
   isForgejoReviewEnabledFn = isForgejoReviewEnabled,
+  fetchReviewBranchFn = fetchReviewBranch,
 } = {}) {
   const flags = args.filter(a => a.startsWith('--'));
   const params = args.filter(a => !a.startsWith('--'));
@@ -57,7 +59,7 @@ async function rebase(args, {
     }
     if (existingRebase.unmergedFiles.length > 0) {
       fmt.log.info('Unmerged files:');
-      existingRebase.unmergedFiles.forEach(file => fmt.log.info(`  - ${file}`));
+      existingRebase.unmergedFiles.forEach((/** @type {string} */ file) => fmt.log.info(`  - ${file}`));
     }
     fmt.log.info('Recovery commands:');
     fmt.log.info(`  ${fmt.command('git rebase --continue')}`);
@@ -68,7 +70,7 @@ async function rebase(args, {
   }
 
   const performPush = async () => {
-    if (!isPush) return;
+    if (!isPush) {return;}
     if (!isForgejoReviewEnabledFn(process.cwd())) {
       fmt.log.info(`Skipping Forgejo push (review provider is not forgejo).`);
       return;
@@ -85,13 +87,13 @@ async function rebase(args, {
     }
     forgejoUser = resolveForgejoUserFn(forgejoUser);
 
-    const token = readTokenFn(forgejoUser);
+    const token = readTokenFn(forgejoUser || 'default');
     if (!token) {
-      fmt.log.fail(`No Forgejo token found for user "${fmt.agent(forgejoUser)}". Push failed.`);
+      fmt.log.fail(`No Forgejo token found for user "${fmt.agent(forgejoUser || 'default')}". Push failed.`);
       exitFn(1);
       return;
     }
-    const result = createPrFn(branch, forgejoUser, token, { rootDir: getPrimaryWorktree(), forceWithLease: true });
+    const result = createPrFn(branch, forgejoUser || 'default', token, { rootDir: getPrimaryWorktree(), forceWithLease: true });
     if (!result.ok) {
       fmt.log.fail(`Push to Forgejo failed: ${result.error}`);
       exitFn(1);
@@ -169,7 +171,9 @@ async function rebase(args, {
   const rootDir = getPrimaryWorktree();
   const worktreePath = resolveWorktree(slug) || conventionalWorktreePath(slug, rootDir);
 
-  const conflictResult = resolveConflictsFn(slug, area, { worktreePathOverride: worktreePath });
+  /** @type{{worktreePathOverride?: string}} */
+  const conflictOpts = { worktreePathOverride: worktreePath };
+  const conflictResult = resolveConflictsFn(slug, area, conflictOpts);
 
   // When rebase is in progress in the worktree, dry merge may fail.
   // Fall back to parsing the rebase output directly.
@@ -200,7 +204,9 @@ async function rebase(args, {
       sharedFiles,
     });
   } else if (!conflictResult.ok) {
-    if (conflictResult.error === 'worktree-missing') {
+    /** @type{{error?: string}} */
+    const cr = conflictResult;
+    if (cr.error === 'worktree-missing') {
       fmt.log.fail(`Mission worktree not found: ${fmt.path(worktreePath)}`);
       fmt.log.info(`Ensure the worktree is registered: ${fmt.command(`git worktree add ${conventionalWorktreePath(slug, getPrimaryWorktree())} ${branch}`)}`);
       exitFn(1);
@@ -221,7 +227,7 @@ async function rebase(args, {
   // Only treat unclassified conflict files as shared-file conflicts
   if (conflictResult.sharedFiles.length === 0 && conflictFiles.length > 0) {
     const classified = new Set([...conflictResult.missionSpecificFiles]);
-    const unclassified = conflictFiles.filter(f => !classified.has(f));
+    const unclassified = conflictFiles.filter((/** @type {string} */ f) => !classified.has(f));
     if (unclassified.length > 0) {
       conflictResult.sharedFiles = unclassified;
     }
@@ -232,10 +238,12 @@ async function rebase(args, {
     fmt.log.info(`All ${conflictResult.missionSpecificFiles.length} conflict(s) are mission-specific. Auto-resolving...`);
     const maxContinueAttempts = 3;
     let continueAttempts = 0;
-    const continueRebase = (opts) => {
+    /** @param {{stdio?: string}} opts */
+    const continueRebase = (/** @type {{stdio?: string}} */ opts = {}) => {
       continueAttempts += 1;
       return gitFn(['-c', 'core.editor=true', '-c', 'merge.autoedit=no', 'rebase', '--continue'], opts);
     };
+    /** @param {{stdout: string, stderr: string, status: number}} result */
     const reportContinueFailure = (result) => {
       const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
       fmt.log.fail(`git rebase --continue failed (status ${result.status}).`);
@@ -251,6 +259,7 @@ async function rebase(args, {
       fmt.log.fail(`Recovery: ${fmt.command('git rebase --abort')}`);
     };
 
+    /** @param {string} branchName */
     const failContinueBudget = (branchName) => {
       fmt.log.fail(`Rebase still in progress on branch ${fmt.branch(branchName || slug)} after ${continueAttempts} failed --continue attempt(s).`);
       fmt.log.fail(`Check rebase state: ${fmt.command('git status')}`);
@@ -415,7 +424,7 @@ async function rebase(args, {
 
   // Shared-file conflicts exist — launch agent to resolve them
   fmt.log.info(`${conflictResult.sharedFiles.length} shared file(s) require agent-assisted resolution:`);
-  conflictResult.sharedFiles.forEach(f => fmt.log.info(`  - ${fmt.path(f)}`));
+  conflictResult.sharedFiles.forEach((/** @type {string} */ f) => fmt.log.info(`  - ${fmt.path(f)}`));
 
   const prompt = buildRebasePrompt({
     slug,
@@ -423,7 +432,7 @@ async function rebase(args, {
     worktreePath,
     missionSpecificFiles: conflictResult.missionSpecificFiles,
     sharedFiles: conflictResult.sharedFiles,
-    gitFn,
+    gitFn: /** @type{Function} */(gitFn),
   });
 
   fmt.log.info('Launching agent for conflict resolution...');
@@ -461,23 +470,24 @@ async function rebase(args, {
  * when a rebase is in progress. Handles all unmerged states:
  * UU (unmerged), DU/UD (modify/delete), AU/UA (add/add), AA (add/add).
  */
+/** @param {string} worktreePath @param {Function} gitFn */
 function parseConflictFilesFromGitStatus(worktreePath, gitFn) {
   const statusResult = gitFn(['-C', worktreePath, 'status', '--porcelain']);
   const files = [];
   const unmergedStates = new Set(['UU', 'DU', 'UD', 'AU', 'UA', 'AA']);
   for (const line of (statusResult.stdout || '').split('\n')) {
     const trimmed = line.trim();
-    if (!trimmed) continue;
+    if (!trimmed) {continue;}
     const match = trimmed.match(/^([A-Z]{2})\s+(.+)$/);
     if (match) {
       const code = match[1];
-      if (!unmergedStates.has(code)) continue;
+      if (!unmergedStates.has(code)) {continue;}
       let file = match[2].trim();
       // Remove surrounding quotes if present
       if ((file.startsWith('"') && file.endsWith('"')) || (file.startsWith("'") && file.endsWith("'"))) {
         file = file.slice(1, -1);
       }
-      if (file) files.push(file);
+      if (file) {files.push(file);}
     }
   }
   return [...new Set(files)];
@@ -487,11 +497,12 @@ function parseConflictFilesFromGitStatus(worktreePath, gitFn) {
  * Parse conflict file paths from git rebase output.
  * Similar to parseConflictFilesFromMergeOutput but handles rebase-specific output.
  */
+/** @param {string} output */
 function parseConflictFilesFromRebaseOutput(output) {
   const seen = new Set();
   const files = [];
   for ( const line of output.split('\n')) {
-    if (!/CONFLICT|KONFLIKT/i.test(line)) continue;
+    if (!/CONFLICT|KONFLIKT/i.test(line)) {continue;}
     // English: "Merge conflict in <file>"
     const inMatch = line.match(/Merge conflict in (.+)$/);
     if (inMatch) {
@@ -539,7 +550,7 @@ function parseConflictFilesFromRebaseOutput(output) {
       const isNonPathPrefix = /^(CONFLICT|KONFLIKT|CONFLICTS|Merge conflict|Sammanslagningskonflikt|Automatic merge|Auto-merging|resolved|merged|deleted|added|changed|modified|rejected|skipped|dropped|superseded|discarded|kept|stashed|applied|already|would|both|ours|yours|their|his|her|its|your|my|us|we|they|he|she|it|a|an|the|but|and|or|for|nor|not|so|yet)\b/i.test(beforeColon);
       if (!isNonPathPrefix) {
         // Skip known advice/hint labels — the rest of the line is not a path.
-        if (/^(tips|hint|note)\b/i.test(beforeColon)) continue;
+        if (/^(tips|hint|note)\b/i.test(beforeColon)) {continue;}
         const f = beforeColon;
         if (f && !seen.has(f)) { seen.add(f); files.push(f); }
       } else if (afterColon) {
@@ -566,12 +577,12 @@ function parseConflictFilesFromRebaseOutput(output) {
 /**
  * Build the prompt for the agent during shared-file conflict resolution.
  */
-function buildRebasePrompt({ slug, area, worktreePath, missionSpecificFiles, sharedFiles, gitFn = null }) {
+/** @param {{slug: string, area: string, worktreePath: string, missionSpecificFiles: string[], sharedFiles: string[], gitFn?: Function}} opts */
+function buildRebasePrompt({ slug, area, worktreePath, missionSpecificFiles, sharedFiles, gitFn = /** @type {Function | undefined} */ (undefined) }) {
   const missionFileCommands = missionSpecificFiles
     .map(f => `  git checkout --theirs "${f}" && git add "${f}"`)
     .join('\n');
   const sharedFileList = sharedFiles.map(f => `  - ${f}`).join('\n');
-  const quotedWorktreePath = `"${worktreePath}"`;
 
   let primaryBranch = 'main';
   try {

package/lib/commands/repair-handoff.js

@@ -1,4 +1,3 @@
-const path = require('path');
 const { git } = require('../core/git');
 const missionUtils = require('../core/mission-utils');
 const rebase = require('./rebase');
@@ -27,6 +26,7 @@ function isRelaunchableError(errorMsg) {
  * @param {string} worktree - Path to the mission worktree
  * @returns {string} The relaunch prompt
  */
+/** @param {string} errorMsg @param {string} slug @param {string} worktree */
 function buildRelaunchPrompt(errorMsg, slug, worktree) {
   const year = missionUtils.getMissionYear(slug, worktree);
   const missionDir = missionUtils.findMissionDir(slug, worktree) || missionUtils.missionDirForSlug(worktree, slug);
@@ -78,23 +78,26 @@ function buildRelaunchPrompt(errorMsg, slug, worktree) {
  * @param {object} [options]
  * @returns {Promise<{repaired: boolean, blocker: string|null}>} Result and optional blocker reason
  */
+/** @param {string} slug @param {string} worktree @param {string} errorMsg @param {{gitFn?: Function, rebaseFn?: Function, log?: Function, error?: Function}} options */
 async function repairHandoff(slug, worktree, errorMsg, options = {}) {
+  /** @type {{gitFn?: Function, rebaseFn?: Function, log?: Function, error?: Function}} */
+  const opts = options;
   const {
-    taskFile = null,
     gitFn = git,
     rebaseFn = rebase,
     log = fmt.log.plain,
     error = fmt.log.plainError
-  } = options;
+  } = opts;
 
   const rootDir = worktree || process.cwd();
   let repaired = false;
   let blocker = null;
 
+  /** @param {string} line */
   function parsePorcelainPath(line) {
     const xy = line.slice(0, 2);
     const rawPath = line.slice(3).trim();
-    const pathPart = rawPath.includes('->') ? rawPath.split('->').pop().trim() : rawPath;
+    const pathPart = rawPath.includes('->') ? (rawPath.split('->').pop() || '').trim() : rawPath;
     const cleanPath = (pathPart.startsWith('"') && pathPart.endsWith('"')) ? pathPart.slice(1, -1) : pathPart;
     return { xy, file: cleanPath };
   }
@@ -128,38 +131,38 @@ async function repairHandoff(slug, worktree, errorMsg, options = {}) {
     const statusResult = gitFn(['-C', rootDir, 'status', '--porcelain']);
     if (statusResult.status === 0 && statusResult.stdout) {
       const dirtyLines = statusResult.stdout.split('\n')
-        .filter(line => line.trim().length > 0);
+        .filter(/** @param {string} line */ (line) => line.trim().length > 0);
 
       const dirtyFilesWithStatus = dirtyLines.map(parsePorcelainPath);
 
-      const unmerged = dirtyFilesWithStatus.filter(f => 
+      const unmerged = dirtyFilesWithStatus.filter((/** @param {{xy: string, file: string}} f */ f =>
         ['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'].includes(f.xy)
-      );
+      ));
 
       if (unmerged.length > 0) {
-        blocker = `Conflicted files detected:\n${unmerged.map(f => `       - ${f.file}`).join('\n')}`;
+        blocker = `Conflicted files detected:\n${unmerged.map((/** @param {{xy: string, file: string}} f */ f => `       - ${f.file}`)).join('\n')}`;
         log(`Cannot auto-commit: ${blocker}`);
         return { repaired: false, blocker };
       }
 
-      const dirtyFiles = dirtyFilesWithStatus.map(f => f.file);
+      const dirtyFiles = dirtyFilesWithStatus.map((/** @param {{xy: string, file: string}} f */ f => f.file));
 
-      const isSafeToCommit = (file) =>
+      const isSafeToCommit = (/** @type{string} */ file) =>
         missionUtils.isWorkflowGeneratedArtifact(file)
         || missionUtils.isMissionArtifact(file, slug, rootDir);
 
       const safeFiles = dirtyFiles.filter(isSafeToCommit);
-      const unsafeFiles = dirtyFiles.filter(f => !isSafeToCommit(f));
+      const unsafeFiles = dirtyFiles.filter((/** @param {string} f */ f => !isSafeToCommit(f)));
 
       if (unsafeFiles.length > 0) {
         log(`Cannot auto-commit: dirty files include non-mission paths:`);
-        unsafeFiles.forEach(f => log(`       - ${f}`));
+        unsafeFiles.forEach((/** @type {string} */ f) => log(`       - ${f}`));
         blocker = `dirty files include non-mission paths: ${unsafeFiles.join(', ')}`;
         return { repaired: false, blocker };
       } else if (safeFiles.length > 0) {
         log(`Auto-committing mission artifacts:`);
-        const stageFailures = [];
-        safeFiles.forEach(f => {
+        const stageFailures = /** @type {string[]} */ ([]);
+        safeFiles.forEach((/** @type {string} */ f) => {
           log(`       - ${f}`);
           const addResult = gitFn(['-C', rootDir, 'add', '--', f]);
           if (addResult.status === 0) {
@@ -195,9 +198,9 @@ async function repairHandoff(slug, worktree, errorMsg, options = {}) {
     try {
       const { getCurrentBranch } = require('../core/git');
       await rebaseFn([slug], {
-        gitFn: (args, opts) => gitFn(args, { ...opts, cwd: rootDir }),
+        gitFn: (/** @type {string[]} */ args, /** @type {{cwd?: string}} */ opts) => gitFn(args, { ...opts, cwd: rootDir }),
         getCurrentBranchFn: () => getCurrentBranch(rootDir),
-        exitFn: (code) => {
+        exitFn: (/** @type {number} */ code) => {
           if (code === 0) {
             rebaseSuccess = true;
           } else {
@@ -205,8 +208,8 @@ async function repairHandoff(slug, worktree, errorMsg, options = {}) {
           }
         }
       });
-    } catch (err) {
-      rebaseError = err.message;
+    } catch (/** @type {unknown} */ err) {
+      rebaseError = /** @type{Error} */(err).message;
     }
 
     if (!rebaseSuccess) {

package/lib/commands/resolve-conflict.js

@@ -4,10 +4,12 @@ const { startAgent } = require('../agents/agents');
 const fmt = require('../core/fmt');
 const { formatVerificationCommand } = require('../core/verification');
 
+/** @param {string} value */
 function shellQuote(value) {
   return `"${String(value).replace(/(["\\$`])/g, '\\$1')}"`;
 }
 
+/** @param {{slug: string, area: string, worktreePath: string, missionSpecificFiles: string[]}} opts */
 function buildAgentResolutionPrompt({ slug, area, worktreePath, missionSpecificFiles }) {
   const fileCommands = missionSpecificFiles
     .map(f => `  git checkout --theirs "${f}" && git add "${f}"`)
@@ -41,10 +43,11 @@ function buildAgentResolutionPrompt({ slug, area, worktreePath, missionSpecificF
   ].join('\n');
 }
 
+/** @param {string[]} args @param {{resolveConflictsFn?: Function, startAgentFn?: Function, exitFn?: Function}} opts */
 async function resolveConflict(args, {
   resolveConflictsFn = resolveConflictsForMission,
   startAgentFn = startAgent,
-  exitFn = (code) => process.exit(code),
+  exitFn = /** @type {(code: number) => void} */ ((code) => process.exit(code)),
 } = {}) {
   const explicitSlug = args[0];
   const slug = inferSlug(explicitSlug);
@@ -69,7 +72,7 @@ async function resolveConflict(args, {
   // Stop and require human intervention.
   if (!result.ok && result.error === 'shared-file-conflicts') {
     fmt.log.fail('Shared-file conflicts require human resolution. Agent cannot guess the correct merge outcome.');
-    fmt.log.info(`Shared files: ${result.sharedFiles.map(f => fmt.path(f)).join(', ')}`);
+    fmt.log.info(`Shared files: ${result.sharedFiles.map(/** @param {string} f */ (f) => fmt.path(f)).join(', ')}`);
     fmt.log.info(`Resolve manually, then re-run: ${fmt.command(`px integrate ${slug} --dry-run`)}`);
     exitFn(1);
     return;

package/lib/commands/review.js

@@ -6,6 +6,7 @@ const review = require('../review/review-commands').review;
  *
  * Usage: node parallix review [<slug>] [--verify] [--submit] [--push] ...
  */
+/** @param {string[]} args */
 async function reviewCommand(args) {
   await review(args);
 }

package/lib/commands/setup-review.js

@@ -6,6 +6,7 @@ const setupReview = require('../tools/setup-review');
  *
  * Usage: node parallix setup-review
  */
+/** @param {string[]} args @param {object} options */
 async function setupReviewCommand(args, options) {
   await setupReview(args, options);
 }