consolidate/compile-check hangs: pdflatex nonstopmode deadlocks on high-error TeX files

[kiki830621]

Bug

macdoc pdf compile-check and macdoc pdf consolidate hang indefinitely when the input .tex file contains many errors.

Root Cause

TexCompileChecker invokes pdflatex -interaction=nonstopmode. On files with 100+ errors:

1. pdflatex hits the hardcoded 100-error limit and emits (That makes 100 errors; please try again.) → Fatal error occurred, no output PDF file produced!
2. However, in nonstopmode, certain error types (group mismatch, missing }) cause pdflatex to not terminate cleanly — it hangs at 0% CPU waiting for something.
3. macdoc's process is waiting for pdflatex's stdout/stderr to close → deadlock.

Observed Behavior

• pdflatex -interaction=nonstopmode hangs (CPU 0%, indefinitely)
• pdflatex -interaction=batchmode completes (exits with error code 1, produces log)
• pdflatex -interaction=scrollmode also completes

Reproduction

# 741-page Wooldridge textbook, AI-transcribed with ~300+ LaTeX errors
macdoc pdf init --pdf wooldridge.pdf --output wooldridge-latex
macdoc pdf segment --project wooldridge-latex
macdoc pdf render --project wooldridge-latex
macdoc pdf blocks --project wooldridge-latex
macdoc pdf transcribe-pages --project wooldridge-latex --backend codex
macdoc pdf chapters --project wooldridge-latex
macdoc pdf assemble --project wooldridge-latex --skip-compile

# These hang:
macdoc pdf compile-check --project wooldridge-latex   # hangs
macdoc pdf consolidate --project wooldridge-latex --agent claude  # hangs at compile step

Suggested Fix

1. Use batchmode instead of nonstopmode in TexCompileChecker — batchmode always terminates
2. Add a timeout (e.g., 120s) to the pdflatex subprocess — kill it if it doesn't exit
3. Pipe stdin from /dev/null to prevent pdflatex from waiting for user input on certain errors

All three would independently fix the deadlock. Combining (1) + (2) would be most robust.

Environment

• macdoc v0.4.0
• pdfTeX 3.141592653-2.6-1.40.27 (TeX Live 2025)
• macOS 15.3 (Darwin 25.3.0)

Current Status

Phase: diagnosed
Last updated: 2026-04-22 by idd-diagnose (batch)

---

Current Status

Phase: implemented
Last updated: 2026-05-02 by idd-implement

Key Decisions

• The code fix belongs in upstream PsychQuant/pdf-to-latex-swift, because macdoc consumes PDFToLaTeXCore as a remote SPM dependency.
• Upstream PR Read .claude guidance for upcoming work #1 implements the consolidate/compile-check hangs: pdflatex nonstopmode deadlocks on high-error TeX files #63 hardening: batchmode, stdin /dev/null, and timeout-backed failed CompileReport.

Scope Changes

• macdoc dependency bump is deferred until the upstream PR is merged and tagged.

Blocking

• Awaiting upstream PR merge/tag, then macdoc dependency update and macdoc-side verification.

Commits

• 14b584f fix: prevent pdflatex compile-check hangs (upstream PsychQuant/pdf-to-latex-swift)

PRs

• Prevent pdflatex compile-check hangs pdf-to-latex-swift#1

[kiki830621]

Diagnosis

Type

bug (P1 — pipeline blocker)

Root Cause / Analysis

Confirmed against source in packages/pdf-to-latex-swift/Sources/PDFToLaTeXCore/TexCompileChecker.swift:134-155:

process.arguments = [
    "pdflatex",
    "-interaction=nonstopmode",
    "-file-line-error",
    filename,
]
// ...
try process.run()
process.waitUntilExit()   // ← blocks forever when pdflatex prompts

Three independently sufficient contributors to the deadlock:

1. -interaction=nonstopmode — some error classes (unclosed {, missing \end{}, dangling $) still cause pdflatex to drop into its * prompt. batchmode does not.
2. No stdin redirection — pdflatex inherits macdoc's stdin. With nothing to read, the * prompt wait turns into an indefinite block.
3. No timeout on waitUntilExit() — once pdflatex is hung, macdoc is hung too.

The reporter's ~300-error Wooldridge fixture hits the hardcoded 100-error ceiling + unmatched group → prompt wait → deadlock.

Impact

• packages/pdf-to-latex-swift/Sources/PDFToLaTeXCore/TexCompileChecker.swift:135-180 (compile(texFileURL:))
• Cascades to Consolidator.swift (calls compile per iteration) → macdoc pdf compile-check and macdoc pdf consolidate both hang.
• Users on any TeX file with severe structural errors cannot run Phase 2 consolidation at all.

Strategy

• Switch -interaction=nonstopmode → -interaction=batchmode at TexCompileChecker.swift:144. Batchmode always terminates and writes the same log format parseLog already expects.
• Redirect stdin: process.standardInput = FileHandle(forReadingAtPath: "/dev/null") before run() (defence in depth — belt + braces).
• Add a configurable timeout (e.g. CompileOptions.timeoutSeconds = 120) using DispatchQueue.global().asyncAfter + process.terminate(); surface as CompileError.timeout so Consolidator can treat it as a hard fail rather than infinite loop.
• Extend Tests/PDFToLaTeXCoreTests/TexCompileCheckerTests.swift with a fixture containing a deliberately unclosed \begin{document} — asserts compile returns within N seconds with success == false.

Complexity

Simple — single-package change in pdf-to-latex-swift, contained to one file + one test fixture. No cross-repo coordination. No spec work required (behaviour-preserving hardening).

Risks

• batchmode suppresses more terminal output than nonstopmode, but macdoc already reads the .log file (TexCompileChecker.swift:158-170), so this is cosmetic at worst.
• Timeout must be high enough for legitimate 700+ page documents (Wooldridge-sized). 120s is a defensible starting default; make it @Option on pdf compile-check so power users can raise it.
• Cross-repo version bump: after fixing in pdf-to-latex-swift, macdoc's Package.swift needs a swift package update and a CLI release. Standard flow per .claude/rules/swift-package-update.md.

[kiki830621]

Implementation Plan

• Work in upstream PsychQuant/pdf-to-latex-swift because macdoc consumes PDFToLaTeXCore via remote SPM dependency, not local packages/ source.
• Modify Sources/PDFToLaTeXCore/TexCompileChecker.swift to run pdflatex in batchmode, redirect stdin from /dev/null, and enforce a configurable timeout that returns a failed CompileReport instead of hanging.
• Extend Tests/PDFToLaTeXCoreTests/TexCompileCheckerTests.swift with compile-path coverage for malformed TeX returning promptly with success == false.
• Run focused and full swift test in pdf-to-latex-swift; open an upstream PR referencing macdoc#63.
• Sync macdoc#63 status with the upstream PR and note that macdoc dependency bump follows after the upstream fix is merged/tagged.

[kiki830621]

Implementation Complete

Checklist (synced from TaskList)

• Work in upstream PsychQuant/pdf-to-latex-swift because macdoc consumes PDFToLaTeXCore via remote SPM dependency -> commit 14b584f
• Modify TexCompileChecker to use batchmode, stdin /dev/null, and configurable timeout -> commit 14b584f
• Add compile-path coverage for malformed TeX and deterministic timeout behavior -> commit 14b584f
• Run focused tests and open upstream PR referencing macdoc#63 -> PR Prevent pdflatex compile-check hangs pdf-to-latex-swift#1
• Sync macdoc#63 with upstream PR status -> this comment

Changes

• 14b584f: pdflatex now runs in batchmode instead of nonstopmode.
• 14b584f: compile checks redirect stdin from /dev/null.
• 14b584f: stuck pdflatex processes terminate after a configurable timeout and return a failed CompileReport with .timeout.
• 14b584f: tests cover malformed TeX returning promptly and a fake long-running pdflatex timeout.

Files Changed

Sources/PDFToLaTeXCore/TexCompileChecker.swift     | 69 ++++++++++++++++++--
Tests/PDFToLaTeXCoreTests/TexCompileCheckerTests.swift | 74 ++++++++++++++++++++++

Verification

• swift test --filter TexCompileCheckerTests -> 12 tests, 0 failures.
• swift test -> blocked by pre-existing LaTeXNormalizerTests failures unrelated to consolidate/compile-check hangs: pdflatex nonstopmode deadlocks on high-error TeX files #63.
• Clean main worktree also fails LaTeXNormalizerTests/testCrossPageDedup, confirming at least part of the full-suite failure is baseline state rather than this branch.

Scope Compliance

No unrelated normalizer or pipeline behavior was changed.

Upstream PR

PsychQuant/pdf-to-latex-swift#1

Next: verification pending

After the upstream PR is merged and tagged, macdoc should update its pdf-to-latex-swift dependency and run macdoc-side build/verification.