@magnusekdahl/parallix 1.1.0 → 1.2.0

package/lib/tools/forgejo.js

@@ -18,9 +18,11 @@ const derivedRepoCache = new Map();
 function codexSandboxHint() {
   return 'Codex runtime cannot reach local Forgejo from Node subprocesses. Use the repo-local Codex config/profile that allows the workflow network path.';
 }
+/** @param {string} rootDir @param {string} remoteName @returns {string} */
 function cacheKey(rootDir, remoteName) {
   return `${rootDir}::${remoteName}`;
 }
+/** @param {string} rootDir @param {string} remoteName @returns {string|null} */
 function deriveRepoFromGitRemote(rootDir, remoteName) {
   if (derivedRepoCache.has(cacheKey(rootDir, remoteName))) {
     return derivedRepoCache.get(cacheKey(rootDir, remoteName));
@@ -46,12 +48,13 @@ function deriveRepoFromGitRemote(rootDir, remoteName) {
   }
 }
 
+/** @param {string} [explicitUser] @returns {string} */
 function resolveForgejoUser(explicitUser) {
   return explicitUser || process.env.FORGEJO_USER || DEFAULT_FORGEJO_USER;
 }
 
 function resolveForgejoHome() {
-  if (process.env.FORGEJO_HOME) return process.env.FORGEJO_HOME;
+  if (process.env.FORGEJO_HOME) {return process.env.FORGEJO_HOME;}
   const directLocal = path.join(process.cwd(), '.forgejo-local');
 
   // In test environments, we MUST NOT fall back to the real Forgejo home.
@@ -83,8 +86,9 @@ function resolveForgejoHome() {
   }
 }
 
+/** @param {string} targetPath @returns {string|null} */
 function normalizePathForComparison(targetPath) {
-  if (!targetPath) return null;
+  if (!targetPath) {return null;}
   try {
     return fs.realpathSync.native(targetPath);
   } catch (_) {
@@ -92,11 +96,16 @@ function normalizePathForComparison(targetPath) {
   }
 }
 
+/**
+ * @param {string} targetPath
+ * @param {{forgejoHome?: string}} [options]
+ * @returns {boolean}
+ */
 function isForgejoPath(targetPath, options = {}) {
   const forgejoHome = options.forgejoHome || resolveForgejoHome();
   const normalizedTarget = normalizePathForComparison(targetPath);
   const normalizedForgejoHome = normalizePathForComparison(forgejoHome);
-  if (!normalizedTarget || !normalizedForgejoHome) return false;
+  if (!normalizedTarget || !normalizedForgejoHome) {return false;}
   return normalizedTarget === normalizedForgejoHome || normalizedTarget.startsWith(normalizedForgejoHome + path.sep);
 }
 
@@ -109,12 +118,21 @@ function resolveForgejoSettings(rootDir = process.cwd()) {
   };
 }
 
+/**
+ * @param {{forgejoUser?: string, token?: string}} options
+ * @returns {{forgejoUser: string, token: string|null}}
+ */
 function resolveForgejoAuth(options = {}) {
   const forgejoUser = resolveForgejoUser(options.forgejoUser);
   const token = options.token || readToken(forgejoUser);
   return { forgejoUser, token };
 }
 
+/**
+ * @param {string} branch
+ * @param {{status?: number, statusCode?: number}} [apiErr]
+ * @returns {string}
+ */
 function formatPrLookupFailure(branch, apiErr = {}) {
   const sandboxNote = apiErr.status === 7 ? ` (${codexSandboxHint()})` : '';
   if (apiErr.statusCode === 401 || apiErr.statusCode === 403) {
@@ -126,7 +144,14 @@ function formatPrLookupFailure(branch, apiErr = {}) {
   return `failed to resolve PR for ${branch}${sandboxNote}`;
 }
 
+/**
+ * @param {string} branch
+ * @param {string} [rootDir]
+ * @param {{forgejoUser?: string, token?: string, apiCall?: Function}} [options]
+ * @returns {{exists: boolean, error?: string, raw: string, number?: number, title?: string, state?: string, merged?: boolean, url?: string}}
+ */
 function getPrStatus(branch, rootDir = process.cwd(), options = {}) {
+  /** @type {{forgejoUser?: string, token?: string, apiCall?: Function}} */
   const {
     forgejoUser,
     token: providedToken,
@@ -198,7 +223,7 @@ function resolveTokenFile(user) {
   ];
 
   for (const candidate of candidates) {
-    if (candidate && fs.existsSync(candidate)) return candidate;
+    if (candidate && fs.existsSync(candidate)) {return candidate;}
   }
 
   return null;
@@ -216,7 +241,7 @@ function readToken(user) {
     return process.env.FORGEJO_TOKEN;
   }
   const tokenFile = resolveTokenFile(resolvedUser);
-  if (!tokenFile) return null;
+  if (!tokenFile) {return null;}
   return fs.readFileSync(tokenFile, 'utf8').trim();
 }
 
@@ -227,7 +252,15 @@ function readToken(user) {
  * @param {string} apiPath  - Path relative to /api/v1/repos/<repo>
  * @param {string} token    - Forgejo PAT
  * @param {object} [body]   - Optional JSON body
- * @returns {{ ok: boolean, data: any, status: number|null }}
+ * @returns {{ ok: boolean, data: any, status: number|null, statusCode: number|null, stderr: string|null, error: string|null }}
+ */
+/**
+ * @param {string} method
+ * @param {string} apiPath
+ * @param {string} token
+ * @param {object} [body]
+ * @param {{rootDir?: string}} [options]
+ * @returns {{ok: boolean, data: any, status: number|null, statusCode: number|null, stderr: string|null, error: string|null}}
  */
 function forgejoApi(method, apiPath, token, body, options = {}) {
   const { rootDir = process.cwd() } = options;
@@ -280,11 +313,22 @@ function forgejoApi(method, apiPath, token, body, options = {}) {
     ok: statusCode >= 200 && statusCode < 300,
     data,
     status: result.status,
-    statusCode
+    statusCode,
+    stderr: result.stderr || null,
+    error: null
   };
 }
 
-function forgejoApiAsync(method, apiPath, token, body, options = {}) {
+/**
+ * @param {string} method
+ * @param {string} apiPath
+ * @param {string} token
+ * @param {object} [body]
+ * @param {{rootDir?: string, timeout?: number}} [options]
+ * @returns {Promise<{ok: boolean, data: any, status: number|null, statusCode: number|null, stderr: string|null, error: string|null}>}
+ */
+async function forgejoApiAsync(method, apiPath, token, body, options = {}) {
+  /** @type {{rootDir?: string, timeout?: number}} */
   const {
     rootDir = process.cwd(),
     timeout = HTTP_REQUEST_TIMEOUT
@@ -297,8 +341,8 @@ function forgejoApiAsync(method, apiPath, token, body, options = {}) {
 
   return new Promise((resolve) => {
     let settled = false;
-    const finish = (result) => {
-      if (settled) return;
+    const finish = /** @param {{ok: boolean, data: any, status: number|null, statusCode: number|null, stderr: string|null, error: string|null}} result */ (result) => {
+      if (settled) {return;}
       settled = true;
       resolve(result);
     };
@@ -311,10 +355,10 @@ function forgejoApiAsync(method, apiPath, token, body, options = {}) {
         'Content-Type': 'application/json',
         ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {})
       }
-    }, (res) => {
+    }, /** @param {import('http').IncomingMessage} res */ (res) => {
       let responseBody = '';
       res.setEncoding('utf8');
-      res.on('data', chunk => {
+      res.on('data', /** @param {string|Buffer} chunk */ (chunk) => {
         responseBody += chunk;
       });
       res.on('end', () => {
@@ -327,22 +371,24 @@ function forgejoApiAsync(method, apiPath, token, body, options = {}) {
           }
         }
         finish({
-          ok: res.statusCode >= 200 && res.statusCode < 300,
+          ok: (res.statusCode || 0) >= 200 && (res.statusCode || 0) < 300,
           data,
           status: 0,
-          statusCode: res.statusCode
+          statusCode: res.statusCode ?? null,
+          stderr: null,
+          error: null
         });
       });
     });
 
-    req.on('error', (error) => {
+    req.on('error', /** @param {{code?: string, message?: string}} error */ (error) => {
       finish({
         ok: false,
         data: null,
         status: null,
         statusCode: null,
-        stderr: error.message,
-        error: ['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH'].includes(error.code) ? codexSandboxHint() : null
+        stderr: error.message || null,
+        error: ['ECONNREFUSED', 'ENOTFOUND', 'EHOSTUNREACH'].includes(error.code || '') ? codexSandboxHint() : null
       });
     });
 
@@ -375,6 +421,13 @@ function forgejoApiAsync(method, apiPath, token, body, options = {}) {
  * @param {object} [options]
  * @returns {{ ok: boolean, url: string|null, error: string|null }}
  */
+/**
+ * @param {string} branch
+ * @param {string} user
+ * @param {string} token
+ * @param {{rootDir?: string, apiCall?: Function, log?: Function, force?: boolean, forceWithLease?: boolean, verificationArea?: string, captureVerifiedTreeProofFn?: Function, assertVerifiedTreeProofFn?: Function}} [options]
+ * @returns {{ok: boolean, url?: string|null, error?: string|null, prNumber?: number}}
+ */
 function createPr(branch, user, token, options = {}) {
   const {
     rootDir = process.cwd(),
@@ -382,7 +435,6 @@ function createPr(branch, user, token, options = {}) {
     log = fmt.log.info,
     force = false,
     forceWithLease = false,
-    gitFetch = fetchReviewBranch,
     verificationArea = null,
     captureVerifiedTreeProofFn = verification.captureVerifiedTreeProof,
     assertVerifiedTreeProofFn = verification.assertVerifiedTreeProof
@@ -394,7 +446,7 @@ function createPr(branch, user, token, options = {}) {
   } catch (_) {
     primaryBranch = 'main';
   }
-  if (branch === primaryBranch) return { ok: false, error: `cannot create a PR from ${primaryBranch}` };
+  if (branch === primaryBranch) {return { ok: false, error: `cannot create a PR from ${primaryBranch}` };}
 
   // Resolve the PR base: for feature-branch missions the PR targets the recorded
   // base branch; for legacy missions it falls back to the primary branch so
@@ -420,7 +472,7 @@ function createPr(branch, user, token, options = {}) {
   const apiUser = user;
   const apiToken = token;
   const resolvedVerificationArea = verificationArea || verification.resolveVerificationAdapter(rootDir).defaultArea;
-  const authenticatedGitFetch = (branchName, dir, options = {}) => fetchReviewBranch(branchName, dir, {
+  const authenticatedGitFetch = /** @param {string} branchName @param {string} dir @param {{user?: string, token?: string}} [options] */ (branchName, dir, options = {}) => fetchReviewBranch(branchName, dir, {
     ...options,
     user: gitUser,
     token: gitToken,
@@ -463,13 +515,13 @@ function createPr(branch, user, token, options = {}) {
   if (!pushArgsResult.ok) {
     return { ok: false, error: pushArgsResult.error };
   }
-  let pushArgs = pushArgsResult.pushArgs;
+  let pushArgs = pushArgsResult.pushArgs || [];
   let pushResult = git.git(pushArgs, { stdio: ['ignore', 'pipe', 'pipe'], env: cLocaleEnv() });
-  if (pushResult.stdout) process.stdout.write(pushResult.stdout);
-  if (pushResult.stderr) process.stderr.write(pushResult.stderr);
+  if (pushResult.stdout) {process.stdout.write(pushResult.stdout);}
+  if (pushResult.stderr) {process.stderr.write(pushResult.stderr);}
 
   if (pushResult.status !== 0) {
-    if (forceWithLease && isStaleInfoPushRejection(pushResult)) {
+    if (forceWithLease && isStaleInfoPushRejection(/** @type {{status?: number, stderr?: string, stdout?: string}} */ (pushResult))) {
       log(`Stale push rejection for ${branch}; fetching and retrying...`);
       pushArgsResult = buildCreatePrPushArgs(branch, remoteUrl, rootDir, {
         force,
@@ -480,10 +532,10 @@ function createPr(branch, user, token, options = {}) {
       if (!pushArgsResult.ok) {
         return { ok: false, error: pushArgsResult.error };
       }
-      pushArgs = pushArgsResult.pushArgs;
+      pushArgs = pushArgsResult.pushArgs || [];
       pushResult = git.git(pushArgs, { stdio: ['ignore', 'pipe', 'pipe'], env: cLocaleEnv() });
-      if (pushResult.stdout) process.stdout.write(pushResult.stdout);
-      if (pushResult.stderr) process.stderr.write(pushResult.stderr);
+      if (pushResult.stdout) {process.stdout.write(pushResult.stdout);}
+      if (pushResult.stderr) {process.stderr.write(pushResult.stderr);}
     }
     if (pushResult.status !== 0) {
       const pushError = (pushResult.stderr || pushResult.stdout || '').trim();
@@ -494,9 +546,9 @@ function createPr(branch, user, token, options = {}) {
   // 3. Check if an OPEN PR already exists for this branch
   const existingPrLookup = resolvePrAccess(branch, apiToken, { apiCall, slug, onlyOpen: true, forgejoUser: apiUser, rootDir });
 
-  if (isApiErrorResult(existingPrLookup)) {
-    const apiErr = existingPrLookup._apiError;
-    return { ok: false, error: `failed to check existing PR: ${apiErr.error || 'API error'}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}` };
+  if (existingPrLookup && isApiErrorResult(existingPrLookup)) {
+    const apiErr = /** @type {{error?: string, status?: number}} */ (existingPrLookup._apiError || {});
+    return { ok: false, error: `failed to check existing PR: ${(apiErr.error || 'API error')}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}` };
   }
 
   // 4. Return existing PR if already present
@@ -526,12 +578,18 @@ function createPr(branch, user, token, options = {}) {
   return { ok: true, url: createResult.data.html_url, prNumber: createResult.data.number };
 }
 
+/**
+ * @param {string} branch
+ * @param {string|null} token
+ * @param {{apiCall?: Function, slug?: string|null, onlyOpen?: boolean, forgejoUser?: string, rootDir?: string}} [options]
+ * @returns {number|null|{_apiError?: object, _notFound?: boolean}}
+ */
 function getPrNumber(branch, token, options = {}) {
   const resolved = resolvePrAccess(branch, token, options);
   if (!resolved || isApiErrorResult(resolved)) {
     return resolved;
   }
-  return resolved.prNumber;
+  return resolved.prNumber ?? null;
 }
 
 /**
@@ -550,7 +608,14 @@ function getPrNumber(branch, token, options = {}) {
  * @param {object} [options]
  * @returns {string|null} The PR author's login, or null if undeterminable.
  */
+/**
+ * @param {string} branch
+ * @param {string} token
+ * @param {{apiCall?: Function, resolvePrNumber?: Function, forgejoUser?: string, rootDir?: string}} [options]
+ * @returns {string|null}
+ */
 function getPrAuthor(branch, token, options = {}) {
+  /** @type {{apiCall?: Function, resolvePrNumber?: Function, forgejoUser?: string, rootDir?: string}} */
   const {
     apiCall = forgejoApi,
     resolvePrNumber = getPrNumber,
@@ -560,13 +625,19 @@ function getPrAuthor(branch, token, options = {}) {
   const slugMatch = branch.match(/^mission\/(task-\d+)/);
   const slug = slugMatch ? slugMatch[1] : null;
   const prNumber = resolvePrNumber(branch, token, { apiCall, slug, forgejoUser, rootDir });
-  if (isApiErrorResult(prNumber) || !prNumber) return null;
+  if (isApiErrorResult(prNumber) || !prNumber) {return null;}
 
   const prRes = apiCall('GET', `/pulls/${prNumber}`, token, undefined, { rootDir });
-  if (!prRes.ok || !prRes.data || !prRes.data.user) return null;
+  if (!prRes.ok || !prRes.data || !prRes.data.user) {return null;}
   return prRes.data.user.login || null;
 }
 
+/**
+ * @param {string} branch
+ * @param {string|null} token
+ * @param {{apiCall?: Function, pageSize?: number, maxPages?: number, slug?: string|null, onlyOpen?: boolean, forgejoUser?: string, rootDir?: string, reportNotFound?: boolean}} [options]
+ * @returns {{prNumber?: number, token?: string, _apiError?: object, _notFound?: boolean}|null}
+ */
 function resolvePrAccess(branch, token, options = {}) {
   const {
     apiCall = forgejoApi,
@@ -581,6 +652,7 @@ function resolvePrAccess(branch, token, options = {}) {
   let lastApiError = null;
   let sawSuccessfulLookup = false;
 
+  /** @param {string} state @param {string} t */
   const searchInState = (state, t) => {
     let consecutiveErrors = 0;
     for (let page = 1; page <= maxPages; page += 1) {
@@ -618,16 +690,17 @@ function resolvePrAccess(branch, token, options = {}) {
     return null;
   };
 
+  /** @param {string} t */
   const doLookup = (t) => {
     const openResult = searchInState('open', t);
-    if (openResult) return openResult;
-    if (!onlyOpen) return searchInState('all', t);
+    if (openResult) {return openResult;}
+    if (!onlyOpen) {return searchInState('all', t);}
     return null;
   };
 
   // 1. Try with the provided token
-  let prNumber = doLookup(token);
-  if (prNumber) return { prNumber, token };
+  let prNumber = doLookup(token || '');
+  if (prNumber) {return { prNumber, token: token || undefined };}
 
   const currentUser = resolveForgejoUser(forgejoUser);
   const triedUsers = [currentUser];
@@ -645,7 +718,7 @@ function resolvePrAccess(branch, token, options = {}) {
       const fallbackToken = readToken(user);
       if (fallbackToken) {
         prNumber = doLookup(fallbackToken);
-        if (prNumber) return { prNumber, token: fallbackToken };
+        if (prNumber) {return { prNumber, token: fallbackToken };}
       }
     }
   }
@@ -656,9 +729,11 @@ function resolvePrAccess(branch, token, options = {}) {
     const settings = resolveForgejoSettings(rootDir);
     fmt.log.info(`Current environment: FORGEJO_URL=${settings.url}, FORGEJO_REPO=${settings.repo}, FORGEJO_HOME=${resolveForgejoHome()}`);
     if (lastApiError) {
-      fmt.log.warn(`API error encountered during lookup: status=${lastApiError.status}, error=${lastApiError.error || 'unknown'}`);
-      if (lastApiError.stderr) {
-        fmt.log.info(`API stderr: ${lastApiError.stderr}`);
+      /** @type {{status?: number, error?: string, stderr?: string|null}} */
+      const err = lastApiError;
+      fmt.log.warn(`API error encountered during lookup: status=${err.status || 0}, error=${err.error || 'unknown'}`);
+      if (err.stderr) {
+        fmt.log.info(`API stderr: ${err.stderr}`);
       }
     }
     fmt.log.info(`curl --version: ${curlCheck.status === 0 ? curlCheck.stdout.split('\n')[0] : 'failed to run curl'}`);
@@ -673,7 +748,14 @@ function resolvePrAccess(branch, token, options = {}) {
   return null;
 }
 
+/**
+ * @param {string} baseSlug
+ * @param {string} token
+ * @param {{apiCall?: Function, pageSize?: number, maxPages?: number}} [options]
+ * @returns {Array<{number: number, title: string, html_url: string, head: string}>}
+ */
 function listOpenPrsForSlug(baseSlug, token, options = {}) {
+  /** @type {{apiCall?: Function, pageSize?: number, maxPages?: number}} */
   const {
     apiCall = forgejoApi,
     pageSize = 50,
@@ -687,11 +769,11 @@ function listOpenPrsForSlug(baseSlug, token, options = {}) {
     const result = apiCall('GET', `/pulls?state=open&page=${page}&limit=${pageSize}&sort=recentupdate&direction=desc`, token);
     if (!result.ok) {
       consecutiveErrors++;
-      if (consecutiveErrors >= 3) break;
+      if (consecutiveErrors >= 3) {break;}
       continue;
     }
     consecutiveErrors = 0;
-    if (!Array.isArray(result.data) || result.data.length === 0) break;
+    if (!Array.isArray(result.data) || result.data.length === 0) {break;}
 
     for (const pr of result.data) {
       const head = pr.head || {};
@@ -709,16 +791,23 @@ function listOpenPrsForSlug(baseSlug, token, options = {}) {
       }
     }
 
-    if (result.data.length < pageSize) break;
+    if (result.data.length < pageSize) {break;}
   }
 
   return prs;
 }
 
+/** @param {{_apiError?: object, _notFound?: boolean}} result @returns {boolean} */
 function isApiErrorResult(result) {
-  return result && typeof result === 'object' && result._apiError && result._notFound === true;
+  return Boolean(result && typeof result === 'object' && result._apiError && result._notFound === true);
 }
 
+/**
+ * @param {string} user
+ * @param {string} token
+ * @param {string} rootDir
+ * @returns {string}
+ */
 function authenticatedReviewUrl(user, token, rootDir = process.cwd()) {
   const { url: forgejoUrl, repo: forgejoRepo } = resolveForgejoSettings(rootDir);
   const url = new URL(forgejoUrl);
@@ -728,23 +817,31 @@ function authenticatedReviewUrl(user, token, rootDir = process.cwd()) {
   return `${protocol}//${user}:${token}@${host}/${forgejoRepo}.git`;
 }
 
+/** @param {string} rootDir @returns {string|null} */
 function reviewRemoteUrl(rootDir = process.cwd()) {
   const { url: forgejoUrl, repo: forgejoRepo } = resolveForgejoSettings(rootDir);
-  if (!forgejoUrl || !forgejoRepo) return null;
+  if (!forgejoUrl || !forgejoRepo) {return null;}
   const url = new URL(forgejoUrl);
   return `${url.protocol}//${url.host}/${forgejoRepo}.git`;
 }
 
+/**
+ * @param {string} user
+ * @param {string} token
+ * @param {string} rootDir
+ * @param {{verificationProof?: object|null, assertVerifiedTreeProofFn?: Function, gitRunner?: Function}} [opts]
+ * @returns {{ok: boolean, skipped?: boolean, status?: number, stderr?: string, error?: string|null}}
+ */
 function syncPrimaryBaseline(user, token, rootDir = process.cwd(), {
   verificationProof = null,
   assertVerifiedTreeProofFn = verification.assertVerifiedTreeProof,
   gitRunner = git.git
 } = {}) {
-  let primaryBranch = 'main';
+  let primaryBranchName = 'main';
   try {
-    primaryBranch = getPrimaryBranch(rootDir);
+    primaryBranchName = getPrimaryBranch(rootDir);
   } catch (_) {
-    primaryBranch = 'main';
+    primaryBranchName = 'main';
   }
 
   const proofCheck = assertVerifiedTreeProofFn(verificationProof, rootDir, { gitRunner });
@@ -752,8 +849,8 @@ function syncPrimaryBaseline(user, token, rootDir = process.cwd(), {
     return { ok: false, error: proofCheck.error || 'verification-proof-mismatch' };
   }
 
-  const primaryExists = gitRunner(['-C', rootDir, 'show-ref', '--verify', '--quiet', `refs/heads/${primaryBranch}`]);
-  if (primaryExists.status !== 0) return { ok: true, skipped: true };
+  const primaryExists = gitRunner(['-C', rootDir, 'show-ref', '--verify', '--quiet', `refs/heads/${primaryBranchName}`]);
+  if (primaryExists.status !== 0) {return { ok: true, skipped: true };}
 
   const remoteUrl = authenticatedReviewUrl(user, token, rootDir);
   // Force-push: the review remote's primary branch is a server-side mirror of our
@@ -761,7 +858,7 @@ function syncPrimaryBaseline(user, token, rootDir = process.cwd(), {
   // sync. Without --force a diverged remote primary (rebases, amended baseline
   // commits) rejects this as a non-fast-forward, aborting the sync and breaking
   // the review loop. See missions/task-1318 "Required Forgejo fix".
-  const result = gitRunner(['-C', rootDir, 'push', '--force', remoteUrl, `${primaryBranch}:${primaryBranch}`], {
+  const result = gitRunner(['-C', rootDir, 'push', '--force', remoteUrl, `${primaryBranchName}:${primaryBranchName}`], {
     stdio: 'pipe'
   });
 
@@ -773,6 +870,14 @@ function syncPrimaryBaseline(user, token, rootDir = process.cwd(), {
   };
 }
 
+/**
+ * @param {string} baseBranch
+ * @param {string} user
+ * @param {string} token
+ * @param {string} rootDir
+ * @param {{gitRunner?: Function}} [opts]
+ * @returns {{ok: boolean, status?: number, stderr?: string, error?: string|null}}
+ */
 function ensureRemoteBaseBranch(baseBranch, user, token, rootDir = process.cwd(), {
   gitRunner = git.git
 } = {}) {
@@ -780,6 +885,7 @@ function ensureRemoteBaseBranch(baseBranch, user, token, rootDir = process.cwd()
   // syncPrimaryBaseline only mirrors the primary branch, so the PR base would
   // not exist on the review remote and PR creation would fail server-side.
   // Mirror the local feature base branch here before the PR is opened.
+  /** @type {{status: number}} */
   const exists = gitRunner(['-C', rootDir, 'show-ref', '--verify', '--quiet', `refs/heads/${baseBranch}`]);
   if (exists.status !== 0) {
     return { ok: false, error: `PR base branch ${baseBranch} does not exist locally` };
@@ -802,6 +908,13 @@ function ensureRemoteBaseBranch(baseBranch, user, token, rootDir = process.cwd()
   };
 }
 
+/**
+ * @param {string} sourceRef
+ * @param {string} destinationRef
+ * @param {string} rootDir
+ * @param {{force?: boolean, forceWithLease?: boolean, user?: string, token?: string}} [opts]
+ * @returns {*}
+ */
 function pushReviewRef(sourceRef, destinationRef, rootDir = process.cwd(), {
   force = false,
   forceWithLease = false,
@@ -811,7 +924,7 @@ function pushReviewRef(sourceRef, destinationRef, rootDir = process.cwd(), {
   const remote = token
     ? authenticatedReviewUrl(user || resolveForgejoUser(), token, rootDir)
     : 'review';
-  const pushArgs = ['-C', rootDir, 'push', remote];
+  const pushArgs = /** @type {string[]} */ (['-C', rootDir, 'push', remote]);
   if (forceWithLease) {
     pushArgs.push('--force-with-lease');
   } else if (force) {
@@ -819,11 +932,17 @@ function pushReviewRef(sourceRef, destinationRef, rootDir = process.cwd(), {
   }
   pushArgs.push(`${sourceRef}:${destinationRef}`);
   const result = git.git(pushArgs, { stdio: ['ignore', 'pipe', 'pipe'] });
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.stdout) {process.stdout.write(result.stdout);}
+  if (result.stderr) {process.stderr.write(result.stderr);}
   return result;
 }
 
+/**
+ * @param {string} branch
+ * @param {string} rootDir
+ * @param {{user?: string, token?: string}} options
+ * @returns {*}
+ */
 function fetchReviewBranch(branch, rootDir = process.cwd(), options = {}) {
   const { user, token } = options;
   const source = token
@@ -839,6 +958,7 @@ function fetchReviewBranch(branch, rootDir = process.cwd(), options = {}) {
   });
 }
 
+/** @param {string} branch @param {string} rootDir @returns {{ok: boolean, ref?: string, sha?: string, error?: string}} */
 function resolveTrackingBranchSha(branch, rootDir = process.cwd()) {
   const candidateRefs = [`refs/remotes/review/${branch}`, `refs/remotes/origin/${branch}`];
   for (const ref of candidateRefs) {
@@ -856,7 +976,15 @@ function resolveTrackingBranchSha(branch, rootDir = process.cwd()) {
   };
 }
 
+/**
+ * @param {string} branch
+ * @param {string} remoteUrl
+ * @param {string} rootDir
+ * @param {{force?: boolean, forceWithLease?: boolean, gitFetch?: Function, refreshTrackingRef?: boolean}} [options]
+ * @returns {{ok: boolean, pushArgs?: string[], error?: string}}
+ */
 function buildCreatePrPushArgs(branch, remoteUrl, rootDir = process.cwd(), options = {}) {
+  /** @type {{force?: boolean, forceWithLease?: boolean, gitFetch?: Function, refreshTrackingRef?: boolean}} */
   const {
     force = false,
     forceWithLease = false,
@@ -911,6 +1039,12 @@ function buildCreatePrPushArgs(branch, remoteUrl, rootDir = process.cwd(), optio
   return { ok: true, pushArgs };
 }
 
+/**
+ * @param {string} branch
+ * @param {string} rootDir
+ * @param {{user?: string, token?: string}} [opts]
+ * @returns {*}
+ */
 function deleteReviewRef(branch, rootDir = process.cwd(), { user, token } = {}) {
   const remote = token
     ? authenticatedReviewUrl(user || resolveForgejoUser(), token, rootDir)
@@ -918,17 +1052,19 @@ function deleteReviewRef(branch, rootDir = process.cwd(), { user, token } = {})
   const result = git.git(['-C', rootDir, 'push', remote, '--delete', branch], {
     stdio: ['ignore', 'pipe', 'pipe']
   });
-  if (result.stdout) process.stdout.write(result.stdout);
-  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.stdout) {process.stdout.write(result.stdout);}
+  if (result.stderr) {process.stderr.write(result.stderr);}
   return result;
 }
 
+/** @param {string} commit @param {string} rootDir @returns {*} */
 function verifyCommitExists(commit, rootDir = process.cwd()) {
   return git.git(['-C', rootDir, 'rev-parse', '--verify', `${commit}^{commit}`], {
     stdio: ['ignore', 'pipe', 'pipe']
   });
 }
 
+/** @param {string} commit @param {string} [remoteRef] @param {string} rootDir @returns {*} */
 function remoteRefContainsCommit(commit, remoteRef = `refs/remotes/review/${getPrimaryBranch(process.cwd())}`, rootDir = process.cwd()) {
   return git.git(['-C', rootDir, 'merge-base', '--is-ancestor', commit, remoteRef], {
     stdio: ['ignore', 'pipe', 'pipe']
@@ -939,10 +1075,12 @@ function remoteRefContainsCommit(commit, remoteRef = `refs/remotes/review/${getP
 // are localized to the operator's locale. We parse these messages to decide
 // control flow, so force a stable C locale on git calls whose stderr we
 // inspect, keeping detection language-independent.
+/** @returns {Record<string, string>} */
 function cLocaleEnv() {
   return { ...process.env, LC_ALL: 'C', LANG: 'C' };
 }
 
+/** @param {{stderr?: string, stdout?: string}} result @returns {string} */
 function pushOutput(result) {
   return [result && result.stderr, result && result.stdout]
     .filter(Boolean)
@@ -955,12 +1093,14 @@ function pushOutput(result) {
 // "fatal: could not find remote ref refs/heads/<branch>". This must be
 // distinguished from real fetch failures (auth/network), which also exit
 // non-zero but do not carry this message and should still abort.
+/** @param {{stderr?: string, stdout?: string}} result @returns {boolean} */
 function isMissingRemoteRef(result) {
   const output = pushOutput(result).toLowerCase();
   return output.includes('could not find remote ref')
     || output.includes("couldn't find remote ref");
 }
 
+/** @param {{status?: number, stderr?: string, stdout?: string}} result @returns {boolean} */
 function isStaleInfoPushRejection(result) {
   return result && result.status !== 0 && /\bstale info\b|\bstale ref\b|fetch first/i.test(pushOutput(result));
 }
@@ -976,6 +1116,14 @@ function isStaleInfoPushRejection(result) {
  * @param {object} [options]    - Optional overrides
  * @returns {{ state: string, submittedAt: string }|null}  Most recent eligible review, or null
  */
+/**
+ * @param {string} branch
+ * @param {string} reviewerUser
+ * @param {string} sinceIso
+ * @param {string} token
+ * @param {{apiCall?: Function, forgejoUser?: string, rootDir?: string}} [options]
+ * @returns {{state: string, submittedAt: string}|null}
+ */
 function getLatestReview(branch, reviewerUser, sinceIso, token, options = {}) {
   const {
     apiCall = forgejoApi,
@@ -986,27 +1134,33 @@ function getLatestReview(branch, reviewerUser, sinceIso, token, options = {}) {
   const slugMatch = branch.match(/^mission\/(task-\d+)/);
   const slug = slugMatch ? slugMatch[1] : null;
   const prAccess = resolvePrAccess(branch, token, { apiCall, slug, forgejoUser, rootDir });
-  if (!prAccess || isApiErrorResult(prAccess)) return null;
+  if (!prAccess || isApiErrorResult(prAccess)) {return null;}
 
   const result = apiCall('GET', `/pulls/${prAccess.prNumber}/reviews`, prAccess.token);
-  if (!result.ok || !Array.isArray(result.data)) return null;
+  if (!result.ok || !Array.isArray(result.data)) {return null;}
 
   const since = new Date(sinceIso).getTime();
 
   const eligible = result.data
-    .filter(r => {
+    .filter(/** @param {{user?: {login?: string}, submitted_at?: string, created_at?: string, state?: string}} r */ r => {
       const user = (r.user || {}).login;
       const submittedAt = r.submitted_at || r.created_at || '';
       const submitted = submittedAt ? new Date(submittedAt).getTime() : 0;
       return user === reviewerUser && submitted >= since;
     })
-    .map(r => ({ state: r.state, submittedAt: r.submitted_at || r.created_at || '' }))
-    .sort((a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
+    .map(/** @param {{state?: string, submitted_at?: string, created_at?: string}} r */ r => ({ state: r.state, submittedAt: r.submitted_at || r.created_at || '' }))
+    .sort(/** @param {{submittedAt: string}} a @param {{submittedAt: string}} b */ (a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
 
   return eligible.length > 0 ? eligible[eligible.length - 1] : null;
 }
 
+/**
+ * @param {string} branch
+ * @param {{forgejoUser?: string, token?: string, apiCall?: Function, rootDir?: string}} [options]
+ * @returns {{ok: boolean, error?: string, reviewState?: string|null, prNumber?: number, defaultUserApproved?: boolean, raw?: string}}
+ */
 function getLatestReviewDecision(branch, options = {}) {
+  /** @type {{forgejoUser?: string, token?: string, apiCall?: Function, rootDir?: string}} */
   const {
     forgejoUser,
     token: providedToken,
@@ -1023,13 +1177,13 @@ function getLatestReviewDecision(branch, options = {}) {
   }
 
   const prAccess = resolvePrAccess(branch, token, { apiCall, slug, forgejoUser, rootDir });
-  if (isApiErrorResult(prAccess)) {
-    const apiErr = prAccess._apiError;
+  if (prAccess && isApiErrorResult(prAccess)) {
+    const apiErr = /** @type {{error?: string, status?: number}} */ (prAccess._apiError || {});
     return {
       ok: false,
       error: 'api-failed',
       reviewState: null,
-      raw: `failed to resolve PR for ${branch}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}`
+      raw: /** @type {string|undefined} */ (`failed to resolve PR for ${branch}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}`)
     };
   }
   if (!prAccess) {
@@ -1046,27 +1200,27 @@ function getLatestReviewDecision(branch, options = {}) {
   // has approved, not the current CLI session user.
   const defaultUserLogin = DEFAULT_FORGEJO_USER;
   const reviews = result.data
-    .map(review => ({
+    .map(/** @param {{user?: {login?: string}, state?: string, submitted_at?: string, created_at?: string, dismissed?: boolean}} review */ (review) => ({
       user: (review.user || {}).login || '?',
       state: review.state || '',
       submittedAt: review.submitted_at || review.created_at || '',
       dismissed: !!review.dismissed
     }))
-    .filter(review => review.state && review.submittedAt && !review.dismissed)
-    .sort((a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
+    .filter(/** @param {{state: string, submittedAt: string, dismissed: boolean}} review */ (review) => review.state && review.submittedAt && !review.dismissed)
+    .sort(/** @param {{submittedAt: string}} a @param {{submittedAt: string}} b */ (a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
 
   if (reviews.length === 0) {
     return { ok: true, prNumber, reviewState: null, defaultUserApproved: false };
   }
 
   // Find the latest formal decision overall
-  const formalReviews = reviews.filter(r => r.state === 'APPROVED' || r.state === 'REQUEST_CHANGES');
+  const formalReviews = reviews.filter(/** @param {{state: string}} r */ (r) => r.state === 'APPROVED' || r.state === 'REQUEST_CHANGES');
 
   const finalState = formalReviews.length > 0
     ? formalReviews[formalReviews.length - 1].state
     : reviews[reviews.length - 1].state;
 
-  const defaultUserApproved = reviews.some(r => r.user === defaultUserLogin && r.state === 'APPROVED');
+  const defaultUserApproved = reviews.some(/** @param {{user: string, state: string}} r */ (r) => r.user === defaultUserLogin && r.state === 'APPROVED');
 
   return {
     ok: true,
@@ -1088,6 +1242,7 @@ function getLatestReviewDecision(branch, options = {}) {
  * @returns {string|null}  Disposition value (CHANGES_MADE|PUSHBACK_ALL|PARKED|BLOCKED) or null
  */
 function getLatestDisposition(branch, implementerUser, sinceIso, token, options = {}) {
+  /** @type {{apiCall?: Function, forgejoUser?: string, rootDir?: string}} */
   const {
     apiCall = forgejoApi,
     forgejoUser,
@@ -1097,80 +1252,82 @@ function getLatestDisposition(branch, implementerUser, sinceIso, token, options
   const slugMatch = branch.match(/^mission\/(task-\d+)/);
   const slug = slugMatch ? slugMatch[1] : null;
   const prAccess = resolvePrAccess(branch, token, { apiCall, slug, forgejoUser, rootDir });
-  if (isApiErrorResult(prAccess)) return null;
-  if (!prAccess) return null;
+  if (prAccess && isApiErrorResult(prAccess)) {return null;}
+  if (!prAccess) {return null;}
   const prNumber = prAccess.prNumber;
 
   const result = apiCall('GET', `/issues/${prNumber}/comments`, prAccess.token);
-  if (!result.ok || !Array.isArray(result.data)) return null;
+  if (!result.ok || !Array.isArray(result.data)) {return null;}
 
   const since = new Date(sinceIso).getTime();
 
   const eligible = result.data
-    .filter(c => {
+    .filter(/** @param {{user?: {login?: string}, created_at?: string, body?: string}} c */ (c) => {
       const user = (c.user || {}).login;
       const createdStr = c.created_at || '';
       const created = createdStr ? new Date(createdStr).getTime() : 0;
       const body = c.body || '';
       return user === implementerUser && created >= since && DISPOSITION_PATTERN.test(body);
     })
-    .map(c => {
-      const match = DISPOSITION_PATTERN.exec(c.body);
+    .map(/** @param {{user?: {login?: string}, created_at?: string, body?: string}} c */ (c) => {
+      const match = DISPOSITION_PATTERN.exec(c.body || '');
       return { disposition: match ? match[1] : null, createdAt: c.created_at || '' };
     })
-    .filter(e => e.disposition)
-    .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+    .filter(/** @param {{disposition: string|null}} e */ (e) => e.disposition)
+    .sort(/** @param {{createdAt: string}} a @param {{createdAt: string}} b */ (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
 
   return eligible.length > 0 ? eligible[eligible.length - 1].disposition : null;
 }
 
-async function getLatestReviewForPr(prNumber, reviewerUser, sinceIso, token, options = {}) {
+async function getLatestReviewForPr(/** @type {number} */ prNumber, /** @type {string} */ reviewerUser, /** @type {string} */ sinceIso, /** @type {string} */ token, options = {}) {
+  /** @type {{apiCall?: Function}} */
   const {
     apiCall = forgejoApiAsync
   } = options;
 
   const result = await apiCall('GET', `/pulls/${prNumber}/reviews`, token);
-  if (!result.ok || !Array.isArray(result.data)) return null;
+  if (!result.ok || !Array.isArray(result.data)) {return null;}
 
   const since = new Date(sinceIso).getTime();
 
   const eligible = result.data
-    .filter(r => {
+    .filter(/** @param {{user?: {login?: string}, submitted_at?: string, created_at?: string, state?: string}} r */ r => {
       const user = (r.user || {}).login;
       const submittedAt = r.submitted_at || r.created_at || '';
       const submitted = submittedAt ? new Date(submittedAt).getTime() : 0;
       return user === reviewerUser && submitted >= since;
     })
-    .map(r => ({ state: r.state, submittedAt: r.submitted_at || r.created_at || '' }))
-    .sort((a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
+    .map(/** @param {{state?: string, submitted_at?: string, created_at?: string}} r */ r => ({ state: r.state, submittedAt: r.submitted_at || r.created_at || '' }))
+    .sort(/** @param {{submittedAt: string}} a @param {{submittedAt: string}} b */ (a, b) => new Date(a.submittedAt).getTime() - new Date(b.submittedAt).getTime());
 
   return eligible.length > 0 ? eligible[eligible.length - 1] : null;
 }
 
-async function getLatestDispositionForPr(prNumber, implementerUser, sinceIso, token, options = {}) {
+async function getLatestDispositionForPr(/** @type {number} */ prNumber, /** @type {string} */ implementerUser, /** @type {string} */ sinceIso, /** @type {string} */ token, options = {}) {
+  /** @type {{apiCall?: Function}} */
   const {
     apiCall = forgejoApiAsync
   } = options;
 
   const result = await apiCall('GET', `/issues/${prNumber}/comments`, token);
-  if (!result.ok || !Array.isArray(result.data)) return null;
+  if (!result.ok || !Array.isArray(result.data)) {return null;}
 
   const since = new Date(sinceIso).getTime();
 
   const eligible = result.data
-    .filter(c => {
+    .filter(/** @param {{user?: {login?: string}, created_at?: string, body?: string}} c */ (c) => {
       const user = (c.user || {}).login;
       const createdAt = c.created_at || '';
       const created = createdAt ? new Date(createdAt).getTime() : 0;
       const body = c.body || '';
       return user === implementerUser && created >= since && DISPOSITION_PATTERN.test(body);
     })
-    .map(c => {
-      const match = DISPOSITION_PATTERN.exec(c.body);
+    .map(/** @param {{user?: {login?: string}, created_at?: string, body?: string}} c */ (c) => {
+      const match = DISPOSITION_PATTERN.exec(c.body || '');
       return { disposition: match ? match[1] : null, createdAt: c.created_at || '' };
     })
-    .filter(e => e.disposition)
-    .sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
+    .filter(/** @param {{disposition: string|null}} e */ (e) => e.disposition)
+    .sort(/** @param {{createdAt: string}} a @param {{createdAt: string}} b */ (a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
 
   return eligible.length > 0 ? eligible[eligible.length - 1].disposition : null;
 }
@@ -1181,9 +1338,10 @@ async function getLatestDispositionForPr(prNumber, implementerUser, sinceIso, to
  * @param {string} branch  - Mission branch (e.g. 'mission/task-089')
  * @param {string} token   - Forgejo PAT
  * @param {string} body    - Comment body (markdown)
- * @returns {{ ok: boolean, data: any, status: number|null }}
+ * @returns {{ ok: boolean, data: any, status: number|null, error?: string, raw?: string }}
  */
 function postComment(branch, token, body, options = {}) {
+  /** @type {{apiCall?: Function, resolvePrNumber?: Function, forgejoUser?: string}} */
   const {
     apiCall = forgejoApi,
     resolvePrNumber = getPrNumber,
@@ -1193,10 +1351,10 @@ function postComment(branch, token, body, options = {}) {
   const slug = slugMatch ? slugMatch[1] : null;
   const prNumber = resolvePrNumber(branch, token, { apiCall, slug, forgejoUser });
   if (isApiErrorResult(prNumber)) {
-    const apiErr = prNumber._apiError;
-    return { ok: false, data: null, status: null, error: 'api-failed', raw: `failed to resolve PR for ${branch}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}` };
+    const apiErr = prNumber._apiError || {};
+    return { ok: false, data: null, status: null, error: 'api-failed', raw: `failed to resolve PR for ${branch}${(apiErr.status || 0) === 7 ? ` (${codexSandboxHint()})` : ''}` };
   }
-  if (!prNumber) return { ok: false, data: null, status: null, error: 'pr-not-found' };
+  if (!prNumber) {return { ok: false, data: null, status: null, error: 'pr-not-found' };}
   return apiCall('POST', `/issues/${prNumber}/comments`, token, { body });
 }
 
@@ -1213,9 +1371,10 @@ const REVIEW_OUTCOME_MAP = {
  * @param {string} token    - Forgejo PAT
  * @param {string} outcome  - 'approve' | 'request-changes' | 'comment'
  * @param {string} summary  - Review summary text
- * @returns {{ ok: boolean, data: any, status: number|null }}
+ * @returns {{ ok: boolean, data: any, status: number|null, error?: string, raw?: string }}
  */
 function postReview(branch, token, outcome, summary, options = {}) {
+  /** @type {{apiCall?: Function, resolvePrNumber?: Function, forgejoUser?: string}} */
   const {
     apiCall = forgejoApi,
     resolvePrNumber = getPrNumber,
@@ -1225,18 +1384,19 @@ function postReview(branch, token, outcome, summary, options = {}) {
   const slug = slugMatch ? slugMatch[1] : null;
   const prNumber = resolvePrNumber(branch, token, { apiCall, slug, forgejoUser });
   if (isApiErrorResult(prNumber)) {
-    const apiErr = prNumber._apiError;
-    return { ok: false, data: null, status: null, error: 'api-failed', raw: `failed to resolve PR for ${branch}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}` };
+    const apiErr = prNumber._apiError || {};
+    return { ok: false, data: null, status: null, error: 'api-failed', raw: `failed to resolve PR for ${branch}${(apiErr.status || 0) === 7 ? ` (${codexSandboxHint()})` : ''}` };
   }
-  if (!prNumber) return { ok: false, data: null, status: null, error: 'pr-not-found' };
+  if (!prNumber) {return { ok: false, data: null, status: null, error: 'pr-not-found' };}
 
   // Resolve current head SHA for the PR to avoid submission failures if PR updated
   const prRes = apiCall('GET', `/pulls/${prNumber}`, token);
   const commit_id = (prRes.ok && prRes.data && prRes.data.head) ? prRes.data.head.sha : null;
 
-  const event = REVIEW_OUTCOME_MAP[outcome];
-  if (!event) return { ok: false, data: null, status: null, error: `unsupported-outcome: ${outcome}` };
+  const event = /** @type {'APPROVED'|'REQUEST_CHANGES'|'COMMENT'|undefined} */ (REVIEW_OUTCOME_MAP[/** @type {keyof typeof REVIEW_OUTCOME_MAP} */ (outcome)]);
+  if (!event) {return { ok: false, data: null, status: null, error: `unsupported-outcome: ${outcome}` };}
 
+  /** @type {{body: string, event: string, commit_id?: string|null}} */
   const payload = { body: summary, event };
   if (commit_id) {
     payload.commit_id = commit_id;
@@ -1260,6 +1420,7 @@ function postReview(branch, token, outcome, summary, options = {}) {
  * @returns {Promise<boolean>} True if Forgejo is reachable, false otherwise
  */
 function forgejoAvailable(url = process.env.FORGEJO_URL || 'http://localhost:3300', options = {}) {
+  /** @type {{request?: Function, timeout?: number}} */
   const {
     request = http.request,
     timeout = HTTP_REQUEST_TIMEOUT
@@ -1267,9 +1428,9 @@ function forgejoAvailable(url = process.env.FORGEJO_URL || 'http://localhost:330
   const targetUrl = new URL(url);
 
   return new Promise((resolve) => {
-    const req = request(targetUrl, { method: 'GET', timeout }, (res) => {
+    const req = request(targetUrl, { method: 'GET', timeout }, (/** @type {import('http').IncomingMessage} */ res) => {
       req.destroy();
-      resolve(res.statusCode !== null && res.statusCode >= 200 && res.statusCode < 300);
+      resolve(res.statusCode !== undefined && res.statusCode >= 200 && res.statusCode < 300);
     });
     req.on('error', () => resolve(false));
     req.on('timeout', () => {
@@ -1280,7 +1441,8 @@ function forgejoAvailable(url = process.env.FORGEJO_URL || 'http://localhost:330
   });
 }
 
-function syncMerged(branch, mergedCommit, options = {}) {
+function syncMerged(/** @type {string} */ branch, /** @type {string} */ mergedCommit, options = {}) {
+  /** @type {{forgejoUser?: string, rootDir?: string, token?: string|null, baseBranch?: string|null, apiCall?: Function, resolvePrNumber?: Function, gitPush?: Function, gitFetch?: Function, gitContainsCommit?: Function, gitDelete?: Function, verifyCommit?: Function, log?: Function}} */
   const {
     forgejoUser,
     rootDir = process.cwd(),
@@ -1304,7 +1466,7 @@ function syncMerged(branch, mergedCommit, options = {}) {
     return { ok: false, error: 'missing-merged-commit' };
   }
 
-  const { token } = resolveForgejoAuth({ forgejoUser, token: providedToken });
+  const { token } = resolveForgejoAuth({ forgejoUser, token: providedToken || undefined });
   if (!token) {
     return { ok: false, error: 'missing-token' };
   }
@@ -1314,11 +1476,11 @@ function syncMerged(branch, mergedCommit, options = {}) {
 
   const prNumber = resolvePrNumber(branch, token, { slug, rootDir });
   if (isApiErrorResult(prNumber)) {
-    const apiErr = prNumber._apiError;
+    const apiErr = prNumber._apiError || {};
     return {
       ok: false,
       error: 'api-failed',
-      raw: `failed to resolve PR for ${branch}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}`
+      raw: `failed to resolve PR for ${branch}${(apiErr.status || 0) === 7 ? ` (${codexSandboxHint()})` : ''}`
     };
   }
   if (!prNumber) {
@@ -1330,7 +1492,7 @@ function syncMerged(branch, mergedCommit, options = {}) {
     return { ok: false, error: 'missing-commit' };
   }
 
-  const verifyMergeState = (statusCode) => {
+  const verifyMergeState = (/** @type {number} */ statusCode) => {
     const prDetails = apiCall('GET', `/pulls/${prNumber}`, token, undefined, { rootDir });
     if (!prDetails.ok) {
       return { ok: false, error: 'merge-verify-failed', prNumber, statusCode: prDetails.statusCode };
@@ -1339,7 +1501,7 @@ function syncMerged(branch, mergedCommit, options = {}) {
     const pr = prDetails.data || {};
     const baseSha = pr.base ? pr.base.sha : null;
     const headSha = pr.head ? pr.head.sha : null;
-    const shaMatch = (a, b) => a && b && (a === b || a.startsWith(b) || b.startsWith(a));
+    const shaMatch = (/** @type {string|null} */ a, /** @type {string|null} */ b) => a && b && (a === b || a.startsWith(b) || b.startsWith(a));
     if (shaMatch(baseSha, mergedCommit) && shaMatch(headSha, mergedCommit)) {
       log(`PR #${prNumber} (${branch}): confirmed head/base match ${mergedCommit} (already merged)`);
       return { ok: true };
@@ -1449,9 +1611,10 @@ function syncMerged(branch, mergedCommit, options = {}) {
  * @param {object} [options]
  * @param {Function} [options.apiCall] - Forgejo API function, injectable for tests
  * @param {Function} [options.log]     - Logger, injectable for tests
- * @returns {Promise<Array|null>} - Array of comment objects sorted by creation time, or null if comments could not be fetched
+ * @returns {any[]|null} - Array of comment objects sorted by creation time, or null if comments could not be fetched
  */
 function getCommentsSync(branch, token, options = {}) {
+  /** @type {{apiCall?: Function, forgejoUser?: string, rootDir?: string, log?: Function}} */
   const {
     apiCall = forgejoApi,
     forgejoUser,
@@ -1461,11 +1624,11 @@ function getCommentsSync(branch, token, options = {}) {
   const slugMatch = branch.match(/^mission\/(task-\d+)/);
   const slug = slugMatch ? slugMatch[1] : null;
   const prAccess = resolvePrAccess(branch, token, { apiCall, slug, forgejoUser, rootDir });
-  if (isApiErrorResult(prAccess)) {
-    logger(`getComments API error resolving PR for ${branch}: status=${prAccess._apiError.status}`);
+  if (prAccess && isApiErrorResult(prAccess)) {
+    logger(`getComments API error resolving PR for ${branch}: status=${(/** @type {{status?: number}} */ (prAccess._apiError || {})).status || 0}`);
     return null;
   }
-  if (!prAccess) return null;
+  if (!prAccess) {return null;}
   const prNumber = prAccess.prNumber;
   const accessToken = prAccess.token;
 
@@ -1479,10 +1642,10 @@ function getCommentsSync(branch, token, options = {}) {
 
   const issueComments = issueCommentsRes.data || [];
   const reviews = reviewsRes.data || [];
-  const allComments = [];
+  const allComments = /** @type {Array<{kind: string, user: string, created: string, body: string, state?: string, location?: string}>} */ ([]);
 
   // 1. Process issue comments
-  issueComments.forEach(c => {
+  issueComments.forEach(/** @param {{user?: {login?: string}, created_at?: string, body?: string}} c */ (c) => {
     allComments.push({
       kind: 'issue-comment',
       user: (c.user || {}).login || '?',
@@ -1494,8 +1657,8 @@ function getCommentsSync(branch, token, options = {}) {
   // 2. Process reviews and their inline comments
   for (const r of reviews) {
     const flags = [];
-    if (r.stale) flags.push('stale');
-    if (r.dismissed) flags.push('dismissed');
+    if (r.stale) {flags.push('stale');}
+    if (r.dismissed) {flags.push('dismissed');}
     const kind = flags.length > 0 ? `review [${flags.join(', ')}]` : 'review';
 
     allComments.push({
@@ -1509,12 +1672,12 @@ function getCommentsSync(branch, token, options = {}) {
     // Fetch inline comments for this review
     const inlineRes = apiCall('GET', `/pulls/${prNumber}/reviews/${r.id}/comments`, accessToken);
     if (inlineRes.ok && Array.isArray(inlineRes.data)) {
-      inlineRes.data.forEach(c => {
+      inlineRes.data.forEach(/** @param {{user?: {login?: string}, created_at?: string, body?: string, path?: string, line?: number, original_line?: number}} c */ (c) => {
         const iFlags = [];
-        if (r.stale) iFlags.push('stale');
-        if (r.dismissed) iFlags.push('dismissed');
+        if (r.stale) {iFlags.push('stale');}
+        if (r.dismissed) {iFlags.push('dismissed');}
         let iKind = 'inline-comment';
-        if (iFlags.length > 0) iKind += ` [${iFlags.join(', ')}]`;
+        if (iFlags.length > 0) {iKind += ` [${iFlags.join(', ')}]`;}
 
         const path = c.path || '';
         const line = c.line || c.original_line || '';
@@ -1531,10 +1694,10 @@ function getCommentsSync(branch, token, options = {}) {
     }
   }
 
-  return allComments.sort((a, b) => a.created.localeCompare(b.created));
+  return allComments.sort(/** @param {{created: string}} a @param {{created: string}} b */ (a, b) => a.created.localeCompare(b.created));
 }
 
-async function getComments(branch, token, options = {}) {
+async function getComments(/** @type {string} */ branch, /** @type {string} */ token, options = {}) {
   return getCommentsSync(branch, token, options);
 }
 
@@ -1544,22 +1707,21 @@ async function getComments(branch, token, options = {}) {
  *
  * @param {string} branch  - Mission branch
  * @param {string} token   - Forgejo PAT
- * @param {string} user    - Forgejo login
  * @returns {Promise<Object>} - { ok: boolean, error: string }
  */
-async function closePr(branch, token, user) {
+async function closePr(branch, token) {
   const slugMatch = branch.match(/^mission\/(task-\d+)/);
   const slug = slugMatch ? slugMatch[1] : null;
   const rootDir = process.cwd();
   const prNumber = getPrNumber(branch, token, { slug, rootDir });
 
-  if (isApiErrorResult(prNumber)) {
-    const apiErr = prNumber._apiError;
-    fmt.log.warn(`API error resolving PR for ${fmt.branch(branch)}: status=${apiErr.status}${apiErr.status === 7 ? ` (${codexSandboxHint()})` : ''}`);
+  if (prNumber && typeof prNumber === 'object' && isApiErrorResult(prNumber)) {
+    const apiErr = /** @type {{status?: number}} */ (prNumber._apiError || {});
+    fmt.log.warn(`API error resolving PR for ${fmt.branch(branch)}: status=${apiErr.status || 0}${(apiErr.status || 0) === 7 ? ` (${codexSandboxHint()})` : ''}`);
     return { ok: true };
   }
 
-  if (prNumber) {
+  if (prNumber && typeof prNumber === 'number') {
     // Check current state
     const prDetails = forgejoApi('GET', `/pulls/${prNumber}`, token, undefined, { rootDir });
     if (prDetails.ok) {
@@ -1619,7 +1781,6 @@ module.exports = {
   verifyCommitExists,
   remoteRefContainsCommit,
   resolveTrackingBranchSha,
-  resolveForgejoHome,
   deriveRepoFromGitRemote,
   resolveForgejoSettings,
   reviewRemoteUrl,