geotechcli 0.4.24 → 0.4.26

package/dist/commands/ingest.js

@@ -1,11 +1,12 @@
-import { basename, parse } from 'node:path';
+import { basename, join, parse } from 'node:path';
 import { writeFileSync } from 'node:fs';
 import { Command } from 'commander';
 import chalk from 'chalk';
-import { approvePersistedBoreholeIngestReview, buildIngestDossier, buildLLMConfig, cancelPersistedIngestJob, computeWeightedPdfPageCost, createAndStartPersistedIngestJob, DEFAULT_LLM_VISION_MODEL, ingestBoreholeLogDocument, ingestGeotechDocument, inspectPdfDocument, listPersistedBoreholeIngestReviewApprovals, listPersistedBoreholeIngestReviews, loadLatestPersistedBoreholeIngestReviewApproval, loadLatestPersistedBoreholeIngestReview, loadPersistedIngestJob, loadPersistedIngestJobResult, loadPersistedBoreholeIngestReviewApproval, loadPersistedBoreholeIngestReview, persistBoreholeIngestReview, promotePersistedBoreholeIngestReview, resolvePersistedIngestJobExtractionConcurrency, renderIngestDossierAsHtml, resumePersistedIngestJob, shouldUseAsyncIngestJob, waitForPersistedIngestJob, } from '@geotechcli/core';
+import { approvePersistedBoreholeIngestReview, buildPersistedIngestJobSegments, buildIngestDossier, buildLLMConfig, cancelPersistedIngestJob, computeWeightedPdfPageCost, createAndStartPersistedIngestJob, DEFAULT_LLM_VISION_MODEL, HOSTED_BETA_EFFECTIVE_PAGE_LIMIT, ingestBoreholeLogDocument, ingestGeotechDocument, inspectPdfDocument, listPersistedBoreholeIngestReviewApprovals, listPersistedBoreholeIngestReviews, loadLatestPersistedBoreholeIngestReviewApproval, loadLatestPersistedBoreholeIngestReview, loadPersistedIngestJob, loadPersistedIngestJobResult, loadPersistedBoreholeIngestReviewApproval, loadPersistedBoreholeIngestReview, persistBoreholeIngestReview, promotePersistedBoreholeIngestReview, resolvePersistedIngestJobExtractionConcurrency, renderIngestDossierAsHtml, resumePersistedIngestJob, shouldSegmentHostedBetaLongPdf, shouldUseAsyncIngestJob, slicePdfInspectionToRange, waitForPersistedIngestJob, writePdfPageSubset, } from '@geotechcli/core';
 import { heading, keyValue, renderJSON, renderTable, success, error, info, warn } from '../ui/terminal.js';
 import { addGlobalFlags, getGlobalFlags } from '../util/flags.js';
 import { estimateHostedBetaVisionBodyBytes, formatByteSize, HOSTED_BETA_REQUEST_LIMIT_BYTES, HOSTED_BETA_REQUEST_SAFE_BYTES, countPdfPages, readVisionInput, readVisionPdfPageInputs, } from '../util/vision-output.js';
+import { openFileInBrowser } from '../ui/browser.js';
 function formatMaybe(value, suffix = '') {
     if (value == null || value === '')
         return 'Unavailable';
@@ -62,8 +63,14 @@ function writeHtmlDossier(result, options) {
     });
     const outputPath = options.outputPath ?? defaultDossierOutputPath(options.sourceLabel);
     writeFileSync(outputPath, renderIngestDossierAsHtml(dossier));
-    success(`HTML ingest dossier saved to ${outputPath}`);
-    return outputPath;
+    const opened = options.open === false ? false : openFileInBrowser(outputPath);
+    success(opened
+        ? `HTML ingest dossier opened in your browser: ${outputPath}`
+        : `HTML ingest dossier saved to ${outputPath}`);
+    return { outputPath, opened };
+}
+function shouldOpenHtmlDossier(flags) {
+    return flags.openInteractivePlot !== false;
 }
 function startProgress(flags, text) {
     if (flags.json || flags.quiet) {
@@ -179,6 +186,30 @@ function asOptionalPositiveInteger(value) {
 function asOptionalTrimmedString(value) {
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function parsePageRange(value) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (!normalized) {
+        return undefined;
+    }
+    const match = normalized.match(/^(\d+)\s*:\s*(\d+)$/);
+    if (!match) {
+        throw new Error(`Invalid --page-range "${String(value)}". Use start:end, for example 61:102.`);
+    }
+    const startPage = Number.parseInt(match[1], 10);
+    const endPage = Number.parseInt(match[2], 10);
+    if (!Number.isInteger(startPage) || !Number.isInteger(endPage) || startPage < 1 || endPage < startPage) {
+        throw new Error(`Invalid --page-range "${String(value)}". Use start:end with positive page numbers.`);
+    }
+    return { startPage, endPage };
+}
+function formatPageRange(range) {
+    if (!range) {
+        return undefined;
+    }
+    const startPage = Array.isArray(range) ? range[0] : range.startPage;
+    const endPage = Array.isArray(range) ? range[1] : range.endPage;
+    return `${startPage}-${endPage}`;
+}
 function getCommandOptionValue(commandLike, key) {
     return typeof commandLike?.getOptionValue === 'function'
         ? commandLike.getOptionValue(key)
@@ -200,6 +231,9 @@ function getRawOptionValue(commandLike, key) {
         if (typeof current !== 'string') {
             continue;
         }
+        if (key === 'open' && current === '--no-open') {
+            return false;
+        }
         if (current === flag) {
             const next = rawArgs[index + 1];
             return typeof next === 'string' && !next.startsWith('--') ? next : true;
@@ -571,15 +605,22 @@ function createPersistedReviewApprovalLookupDryRun(projectId, reviewDatasetName,
     };
 }
 function resolveCommandOptions(opts, commandLike, extraKeys = []) {
-    const resolvedOpts = typeof commandLike?.optsWithGlobals === 'function'
-        ? commandLike.optsWithGlobals()
+    const commandSource = commandLike ?? opts;
+    const rawOpts = isRecord(opts) && typeof opts.optsWithGlobals !== 'function'
+        ? opts
+        : {};
+    const resolvedOpts = typeof commandSource?.optsWithGlobals === 'function'
+        ? commandSource.optsWithGlobals()
         : undefined;
     const resolved = {
-        ...(isRecord(opts) ? opts : {}),
+        ...rawOpts,
         ...(isRecord(resolvedOpts) ? resolvedOpts : {}),
     };
-    for (const key of ['json', 'quiet', 'dryRun', 'output', ...extraKeys]) {
-        const value = getRawOptionValue(commandLike, key) ?? getCommandOptionValue(opts, key) ?? getCommandOptionValue(commandLike, key);
+    for (const key of ['json', 'quiet', 'dryRun', 'output', 'open', 'noOpen', ...extraKeys]) {
+        if (resolved[key] !== undefined) {
+            continue;
+        }
+        const value = getRawOptionValue(commandSource, key) ?? getCommandOptionValue(rawOpts, key) ?? getCommandOptionValue(commandSource, key);
         if (value !== undefined) {
             resolved[key] = value;
         }
@@ -838,6 +879,43 @@ function normalizeIngestJobRecord(value) {
                 : undefined,
         }
         : undefined;
+    const segmentation = isRecord(value.segmentation)
+        ? {
+            mode: asOptionalTrimmedString(value.segmentation.mode) ?? 'single',
+            pageRange: Array.isArray(value.segmentation.pageRange)
+                && value.segmentation.pageRange.length === 2
+                && typeof value.segmentation.pageRange[0] === 'number'
+                && typeof value.segmentation.pageRange[1] === 'number'
+                ? [value.segmentation.pageRange[0], value.segmentation.pageRange[1]]
+                : undefined,
+            effectivePageLimit: asOptionalPositiveInteger(value.segmentation.effectivePageLimit),
+            segmentCount: asOptionalPositiveInteger(value.segmentation.segmentCount),
+            segments: Array.isArray(value.segmentation.segments)
+                ? value.segmentation.segments.flatMap((segment) => {
+                    if (!isRecord(segment)) {
+                        return [];
+                    }
+                    const segmentIndex = asOptionalPositiveInteger(segment.segmentIndex);
+                    const startPage = asOptionalPositiveInteger(segment.startPage);
+                    const endPage = asOptionalPositiveInteger(segment.endPage);
+                    if (segmentIndex == null || startPage == null || endPage == null) {
+                        return [];
+                    }
+                    return [{
+                            segmentIndex,
+                            startPage,
+                            endPage,
+                            status: asOptionalTrimmedString(segment.status),
+                            childJobId: asOptionalTrimmedString(segment.childJobId),
+                            completedPages: asOptionalPositiveInteger(segment.completedPages),
+                            failedPages: typeof segment.failedPages === 'number' && Number.isFinite(segment.failedPages)
+                                ? segment.failedPages
+                                : undefined,
+                        }];
+                })
+                : [],
+        }
+        : undefined;
     return {
         jobId,
         documentType,
@@ -854,6 +932,12 @@ function normalizeIngestJobRecord(value) {
             weightedPageCost: typeof source.weightedPageCost === 'number' && Number.isFinite(source.weightedPageCost)
                 ? source.weightedPageCost
                 : 0,
+            pageRange: Array.isArray(source.pageRange)
+                && source.pageRange.length === 2
+                && typeof source.pageRange[0] === 'number'
+                && typeof source.pageRange[1] === 'number'
+                ? [source.pageRange[0], source.pageRange[1]]
+                : undefined,
         },
         processing: {
             pagePreprocessingConcurrency: asOptionalPositiveInteger(processing.pagePreprocessingConcurrency) ?? 0,
@@ -870,6 +954,7 @@ function normalizeIngestJobRecord(value) {
             lastError: asOptionalTrimmedString(execution.lastError),
             cancelRequested: execution.cancelRequested === true,
         },
+        segmentation,
         pageCounts,
         pages,
         result,
@@ -883,6 +968,18 @@ function renderIngestJobRecord(job, options) {
     keyValue('Source', job.source.fileName ?? job.source.filePath ?? 'Unknown');
     keyValue('Pages', String(job.source.totalPages));
     keyValue('Weighted page cost', String(job.source.weightedPageCost));
+    if (job.source.pageRange) {
+        keyValue('Selected range', formatPageRange(job.source.pageRange) ?? 'Unavailable');
+    }
+    if (job.segmentation && job.segmentation.mode !== 'single') {
+        keyValue('Segmentation mode', job.segmentation.mode);
+        if (job.segmentation.segmentCount) {
+            keyValue('Segments', String(job.segmentation.segmentCount));
+        }
+        if (job.segmentation.effectivePageLimit) {
+            keyValue('Effective-page window', String(job.segmentation.effectivePageLimit));
+        }
+    }
     keyValue('Completed pages', String(job.pageCounts.completed));
     keyValue('Failed pages', String(job.pageCounts.failed));
     keyValue('Pending pages', String(job.pageCounts.pending));
@@ -922,6 +1019,17 @@ function renderIngestJobRecord(job, options) {
     if (job.result?.persistedReview?.datasetName) {
         keyValue('Stored review', job.result.persistedReview.datasetName);
     }
+    if (job.segmentation?.segments.length) {
+        console.log('');
+        console.log(chalk.white('  Segments:'));
+        renderTable(['Segment', 'Pages', 'Status', 'Completed', 'Failed'], job.segmentation.segments.map((segment) => [
+            String(segment.segmentIndex),
+            `${segment.startPage}-${segment.endPage}`,
+            segment.status ?? 'queued',
+            segment.completedPages != null ? String(segment.completedPages) : '-',
+            segment.failedPages != null ? String(segment.failedPages) : '-',
+        ]));
+    }
     const downgradedPages = job.pages.filter((page) => page.downgraded);
     const failedPages = job.pages.filter((page) => page.status === 'failed');
     if (failedPages.length > 0) {
@@ -983,6 +1091,81 @@ function renderIngestJobResult(job) {
         persistedReview,
     });
 }
+function renderCompactIngestResultSummary(result, options = {}) {
+    heading(options.title ?? 'Geotechnical Ingest Result');
+    keyValue('Document type', result.documentType);
+    keyValue('Source', options.sourceLabel ?? result.source.fileName ?? result.source.filePath ?? 'Unknown');
+    keyValue('Pages processed', `${result.source.successfulPages}/${result.source.totalPages}`);
+    if (result.documentType === 'geotech-document') {
+        keyValue('Materials', String(result.materials.length));
+        keyValue('Parameters', String(result.parameters.length));
+    }
+    else {
+        keyValue('Boreholes extracted', String(result.boreholes.length));
+    }
+    keyValue('Confidence', `${result.confidence}%`);
+    keyValue('Review required', result.reviewRequired ? 'Yes' : 'No');
+    keyValue('Auto proceed', result.canAutoProceed ? 'Yes' : 'No');
+    if (options.persistedReview) {
+        keyValue('Stored review', options.persistedReview.datasetName);
+    }
+    if (options.htmlDossier) {
+        keyValue('HTML dossier', options.htmlDossier.outputPath);
+        keyValue('Opened', options.htmlDossier.opened ? 'Yes' : 'No');
+    }
+    console.log('');
+}
+function formatIngestJobProgress(job) {
+    const knownPageCount = job.pageCounts.completed + job.pageCounts.failed + job.pageCounts.pending;
+    const totalPages = Math.max(job.source.totalPages, knownPageCount, 1);
+    const resolvedPages = Math.min(totalPages, job.pageCounts.completed + job.pageCounts.failed);
+    const pendingPages = Math.max(job.pageCounts.pending, totalPages - resolvedPages);
+    const failedText = job.pageCounts.failed > 0 ? `, ${job.pageCounts.failed} failed` : '';
+    const segments = job.segmentation?.segments ?? [];
+    const segmentText = segments.length > 0
+        ? `, ${segments.filter((segment) => segment.status === 'completed' || segment.status === 'failed').length}/${segments.length} segments resolved`
+        : '';
+    return `Ingest progress: ${resolvedPages}/${totalPages} pages resolved (${job.pageCounts.completed} completed${failedText}, ${pendingPages} pending${segmentText}) - ${job.status}`;
+}
+function isWaitTimeoutError(err, jobId) {
+    return err instanceof Error
+        && err.message.includes(`Timed out while waiting for persisted ingest job "${jobId}"`);
+}
+async function waitForPersistedIngestJobWithLiveProgress(jobId, flags) {
+    if (flags.json || flags.quiet) {
+        return waitForPersistedIngestJob(jobId);
+    }
+    info(`Waiting for ingest job ${jobId} to finish...`);
+    let lastProgress = '';
+    while (true) {
+        try {
+            const record = await waitForPersistedIngestJob(jobId, { pollMs: 250, timeoutMs: 1000 });
+            const normalized = normalizeIngestJobRecord(record);
+            if (normalized) {
+                const progress = formatIngestJobProgress(normalized);
+                if (progress !== lastProgress) {
+                    info(progress);
+                }
+            }
+            return record;
+        }
+        catch (err) {
+            if (!isWaitTimeoutError(err, jobId)) {
+                throw err;
+            }
+            const record = loadPersistedIngestJob(jobId);
+            const normalized = normalizeIngestJobRecord(record);
+            if (!normalized) {
+                continue;
+            }
+            const progress = formatIngestJobProgress(normalized);
+            if (progress !== lastProgress) {
+                info(progress);
+                lastProgress = progress;
+            }
+        }
+    }
+}
 export function registerIngestCommand(program) {
     const cmd = new Command('ingest')
         .description('Extract structured geotechnical data from image/PDF documents')
@@ -990,13 +1173,16 @@ export function registerIngestCommand(program) {
         .argument('<file>', 'Path to a geotechnical image or PDF document')
         .option('--type <type>', 'Document type to ingest', 'borehole-log')
         .option('--format <format>', 'Result presentation format: plain or html', 'plain')
+        .option('--page-range <start:end>', 'Restrict PDF ingest to a contiguous page range, for example 61:102')
         .option('--borehole-id <id>', 'Override borehole ID for a single continuous borehole log')
         .option('--project <id>', 'Persist the ingest review into a stored project')
+        .option('--background', 'Create a resumable ingest job and return immediately')
         .action(async (filePath, opts) => {
         const flags = getGlobalFlags(opts);
         const outputFormat = resolveIngestPresentationFormat(opts.format);
         assertIngestPresentationMode(flags, outputFormat);
         const wantsHtmlDossier = shouldRenderHtmlDossier(outputFormat, flags.output);
+        const runJobInBackground = Boolean(opts.background) || flags.json || flags.quiet;
         const documentType = String(opts.type ?? 'borehole-log').toLowerCase();
         const supportedTypes = new Set(['borehole-log', 'geotech-document']);
         if (!supportedTypes.has(documentType)) {
@@ -1006,6 +1192,13 @@ export function registerIngestCommand(program) {
         try {
             const file = readVisionInput(filePath);
             describeVisionInput(file, flags);
+            const config = buildLLMConfig();
+            const selectedPageRange = file.kind === 'pdf'
+                ? parsePageRange(opts.pageRange)
+                : undefined;
+            if (selectedPageRange && file.kind !== 'pdf') {
+                throw new Error('--page-range is only supported for PDF ingest.');
+            }
             let countedPdfPages = null;
             if (file.kind === 'pdf') {
                 try {
@@ -1015,21 +1208,63 @@ export function registerIngestCommand(program) {
                     countedPdfPages = null;
                 }
             }
-            const shouldShortCircuitAsyncInspection = file.kind === 'pdf'
-                && countedPdfPages != null
-                && countedPdfPages > 5;
-            const inspection = file.kind === 'pdf' && (!shouldShortCircuitAsyncInspection || countedPdfPages == null)
+            if (selectedPageRange && countedPdfPages != null && selectedPageRange.endPage > countedPdfPages) {
+                throw new Error(`--page-range ${selectedPageRange.startPage}:${selectedPageRange.endPage} exceeds the PDF page count (${countedPdfPages}).`);
+            }
+            const shouldInspectPdf = file.kind === 'pdf'
+                && (selectedPageRange != null
+                    || countedPdfPages == null
+                    || countedPdfPages <= 5
+                    || documentType === 'geotech-document');
+            const inspection = file.kind === 'pdf' && shouldInspectPdf
                 ? inspectPdfDocument(filePath)
                 : null;
-            const effectiveInspection = inspection && inspection.totalPages > 0 ? inspection : null;
-            const totalPages = countedPdfPages
+            const fullInspection = inspection && inspection.totalPages > 0 ? inspection : null;
+            if (file.kind === 'pdf' && countedPdfPages == null && !fullInspection && !selectedPageRange) {
+                throw new Error('Could not determine the PDF page count. The file may be encrypted, damaged, or use an unsupported PDF structure.');
+            }
+            if (selectedPageRange && fullInspection && selectedPageRange.endPage > fullInspection.totalPages) {
+                throw new Error(`--page-range ${selectedPageRange.startPage}:${selectedPageRange.endPage} exceeds the PDF page count (${fullInspection.totalPages}).`);
+            }
+            const effectiveInspection = fullInspection && selectedPageRange
+                ? slicePdfInspectionToRange(fullInspection, selectedPageRange)
+                : fullInspection;
+            const totalPages = effectiveInspection?.totalPages
+                ?? countedPdfPages
+                ?? (selectedPageRange ? (selectedPageRange.endPage - selectedPageRange.startPage + 1) : null)
+                ?? fullInspection?.totalPages
                 ?? effectiveInspection?.totalPages
                 ?? 1;
             const weightedPageCost = file.kind === 'pdf'
                 ? (effectiveInspection ? computeWeightedPdfPageCost(effectiveInspection) : totalPages)
                 : 1;
+            const shouldCreateSegmentedParent = file.kind === 'pdf'
+                && shouldSegmentHostedBetaLongPdf(documentType, config, fullInspection, selectedPageRange);
+            const segmentationSummary = shouldCreateSegmentedParent && fullInspection
+                ? {
+                    mode: 'segmented-parent',
+                    pageRange: [
+                        selectedPageRange?.startPage ?? 1,
+                        selectedPageRange?.endPage ?? fullInspection.totalPages,
+                    ],
+                    effectivePageLimit: HOSTED_BETA_EFFECTIVE_PAGE_LIMIT,
+                    segmentCount: buildPersistedIngestJobSegments(fullInspection, {
+                        pageRange: selectedPageRange,
+                        effectivePageLimit: HOSTED_BETA_EFFECTIVE_PAGE_LIMIT,
+                    }).length,
+                    segments: buildPersistedIngestJobSegments(fullInspection, {
+                        pageRange: selectedPageRange,
+                        effectivePageLimit: HOSTED_BETA_EFFECTIVE_PAGE_LIMIT,
+                    }).map((segment, index, segments) => ({
+                        ...segment,
+                        segmentIndex: index + 1,
+                        segmentCount: segments.length,
+                        status: 'queued',
+                    })),
+                }
+                : undefined;
             const shouldRunAsJob = file.kind === 'pdf'
-                && (shouldShortCircuitAsyncInspection || shouldUseAsyncIngestJob(effectiveInspection, totalPages));
+                && (shouldCreateSegmentedParent || shouldUseAsyncIngestJob(effectiveInspection, totalPages));
             if (flags.dryRun) {
                 if (shouldRunAsJob) {
                     const dryRun = {
@@ -1044,7 +1279,9 @@ export function registerIngestCommand(program) {
                         weightedPageCost,
                         wouldCreateBackgroundJob: true,
                         pagePreprocessingConcurrency: 2,
-                        chunkExtractionConcurrency: resolvePersistedIngestJobExtractionConcurrency(buildLLMConfig()),
+                        chunkExtractionConcurrency: resolvePersistedIngestJobExtractionConcurrency(config, effectiveInspection, segmentationSummary),
+                        pageRange: selectedPageRange ? [selectedPageRange.startPage, selectedPageRange.endPage] : undefined,
+                        segmentation: segmentationSummary,
                         pageClassifications: effectiveInspection?.pages.map((page) => ({
                             pageNumber: page.pageNumber,
                             classification: page.classification,
@@ -1062,6 +1299,12 @@ export function registerIngestCommand(program) {
                     keyValue('Pages', String(totalPages));
                     keyValue('Weighted page cost', String(weightedPageCost));
                     keyValue('Would create background job', 'Yes');
+                    if (selectedPageRange) {
+                        keyValue('Selected range', formatPageRange(selectedPageRange) ?? 'Unavailable');
+                    }
+                    if (segmentationSummary?.segments?.length) {
+                        keyValue('Segmentation', `Hosted-beta best-result window is ${HOSTED_BETA_EFFECTIVE_PAGE_LIMIT} effective pages; processing as ${segmentationSummary.segments.map((segment) => `${segment.startPage}-${segment.endPage}`).join(', ')}`);
+                    }
                     if (opts.project) {
                         keyValue('Project', String(opts.project));
                     }
@@ -1081,6 +1324,7 @@ export function registerIngestCommand(program) {
                     wouldUseHostedVision: true,
                     projectId: opts.project,
                     totalPages,
+                    pageRange: selectedPageRange ? [selectedPageRange.startPage, selectedPageRange.endPage] : undefined,
                     pageClassifications: effectiveInspection?.pages.map((page) => ({
                         pageNumber: page.pageNumber,
                         classification: page.classification,
@@ -1099,6 +1343,9 @@ export function registerIngestCommand(program) {
                 keyValue('Source', filePath);
                 keyValue('Input kind', file.kind === 'pdf' ? 'pdf' : 'image');
                 keyValue('Pages', String(dryRun.totalPages));
+                if (selectedPageRange) {
+                    keyValue('Selected range', formatPageRange(selectedPageRange) ?? 'Unavailable');
+                }
                 if (opts.project) {
                     keyValue('Project', String(opts.project));
                 }
@@ -1115,18 +1362,20 @@ export function registerIngestCommand(program) {
                 return;
             }
             if (shouldRunAsJob) {
-                if (wantsHtmlDossier && flags.output) {
+                if (runJobInBackground && wantsHtmlDossier) {
                     throw new Error('HTML ingest dossiers are generated from completed results. Start the job first, then run geotech ingest wait <jobId> --format html --output <file>.');
                 }
                 spinner = startProgress(flags, 'Creating resumable ingest job...');
-                const config = buildLLMConfig();
                 const job = createAndStartPersistedIngestJob({
                     documentType: documentType,
                     filePath,
                     inspection: effectiveInspection,
+                    totalPagesFallback: totalPages,
                     config,
                     projectId: opts.project,
                     overrideBoreholeId: opts.boreholeId,
+                    pageRange: selectedPageRange ? [selectedPageRange.startPage, selectedPageRange.endPage] : undefined,
+                    segmentation: segmentationSummary,
                 });
                 const normalizedJob = normalizeIngestJobRecord(job);
                 spinner?.succeed(`Ingest job started: ${job.jobId}`);
@@ -1134,20 +1383,65 @@ export function registerIngestCommand(program) {
                     renderJSON(job);
                     return;
                 }
-                if (normalizedJob) {
+                if (runJobInBackground && normalizedJob && !flags.quiet) {
                     renderIngestJobRecord(normalizedJob, {
                         title: 'Geotechnical Ingest Job Started',
                         includeCommands: true,
                     });
                 }
-                if (flags.output) {
+                if (runJobInBackground && segmentationSummary?.segments?.length && !flags.quiet) {
+                    info(`Hosted-beta best-result window is ${HOSTED_BETA_EFFECTIVE_PAGE_LIMIT} effective pages; processing as linked segments ${segmentationSummary.segments.map((segment) => `${segment.startPage}-${segment.endPage}`).join(' and ')}.`);
+                }
+                if (runJobInBackground && flags.output) {
                     writeFileSync(flags.output, JSON.stringify(job, null, 2));
-                    success(`Job details saved to ${flags.output}`);
+                    if (!flags.quiet) {
+                        success(`Job details saved to ${flags.output}`);
+                    }
+                }
+                if (runJobInBackground) {
+                    return;
+                }
+                const waitedRecord = await waitForPersistedIngestJobWithLiveProgress(job.jobId, flags);
+                const completedJob = normalizeIngestJobRecord(waitedRecord);
+                if (!completedJob) {
+                    throw new Error(`Persisted ingest job "${job.jobId}" could not be normalized.`);
+                }
+                if (completedJob.status !== 'completed' || !completedJob.result?.ingestResult) {
+                    renderIngestJobRecord(completedJob, { title: 'Geotechnical Ingest Job Status', includeCommands: true });
+                    throw new Error(`Persisted ingest job "${job.jobId}" finished with status "${completedJob.status}".`);
+                }
+                const completedResult = completedJob.result.ingestResult;
+                const persistedReview = completedJob.result.persistedReview
+                    ? {
+                        projectId: completedJob.request.projectId ?? 'Unknown',
+                        datasetName: completedJob.result.persistedReview.datasetName,
+                        reviewId: completedJob.result.persistedReview.reviewId,
+                        createdAt: completedJob.result.persistedReview.createdAt,
+                    }
+                    : null;
+                if (wantsHtmlDossier) {
+                    const htmlDossier = writeHtmlDossier(completedResult, {
+                        outputPath: flags.output,
+                        open: shouldOpenHtmlDossier(flags),
+                        sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? completedJob.jobId,
+                        storedReview: persistedReview,
+                    });
+                    renderCompactIngestResultSummary(completedResult, {
+                        sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? completedJob.jobId,
+                        persistedReview,
+                        htmlDossier,
+                    });
+                }
+                else {
+                    renderIngestJobResult(completedJob);
+                    if (flags.output) {
+                        writeFileSync(flags.output, JSON.stringify(completedJob.result, null, 2));
+                        success(`Results saved to ${flags.output}`);
+                    }
                 }
                 return;
             }
             spinner = startProgress(flags, 'Running geotechnical ingest...');
-            const config = buildLLMConfig();
             const requestDetails = {
                 prompt: documentType === 'borehole-log'
                     ? 'Extract structured borehole log data.'
@@ -1158,7 +1452,16 @@ export function registerIngestCommand(program) {
             };
             const result = file.kind === 'pdf'
                 ? await (async () => {
-                    const pageInputs = await readVisionPdfPageInputs(filePath, { inspection: effectiveInspection });
+                    const scopedInspection = selectedPageRange && fullInspection
+                        ? slicePdfInspectionToRange(fullInspection, selectedPageRange, { rebasePageNumbers: true })
+                        : effectiveInspection;
+                    const pdfInputPath = selectedPageRange
+                        ? join(process.cwd(), 'tmp', 'cli-page-ranges', `${slugifyOutputStem(basename(filePath))}-pages-${selectedPageRange.startPage}-${selectedPageRange.endPage}.pdf`)
+                        : filePath;
+                    if (selectedPageRange) {
+                        await writePdfPageSubset(filePath, selectedPageRange, pdfInputPath);
+                    }
+                    const pageInputs = await readVisionPdfPageInputs(pdfInputPath, { inspection: scopedInspection });
                     for (const pageInput of pageInputs) {
                         maybeCheckHostedBetaVisionPayload(config, pageInput, requestDetails);
                     }
@@ -1169,9 +1472,10 @@ export function registerIngestCommand(program) {
                                 filePath,
                                 fileName: basename(filePath),
                                 inputKind: 'pdf',
+                                pageRange: selectedPageRange ? [selectedPageRange.startPage, selectedPageRange.endPage] : undefined,
                             },
                             overrideBoreholeId: opts.boreholeId,
-                            inspection: effectiveInspection,
+                            inspection: scopedInspection,
                             pages: pageInputs,
                         })
                         : ingestGeotechDocument({
@@ -1180,8 +1484,9 @@ export function registerIngestCommand(program) {
                                 filePath,
                                 fileName: basename(filePath),
                                 inputKind: 'pdf',
+                                pageRange: selectedPageRange ? [selectedPageRange.startPage, selectedPageRange.endPage] : undefined,
                             },
-                            inspection: effectiveInspection,
+                            inspection: scopedInspection,
                             pages: pageInputs,
                         });
                 })()
@@ -1247,6 +1552,7 @@ export function registerIngestCommand(program) {
             if (wantsHtmlDossier) {
                 writeHtmlDossier(result, {
                     outputPath: flags.output,
+                    open: shouldOpenHtmlDossier(flags),
                     sourceLabel: result.source.fileName ?? result.source.filePath ?? filePath,
                     storedReview: persistedReviewDetails,
                 });
@@ -1333,6 +1639,7 @@ export function registerIngestCommand(program) {
                 const dossierDetails = buildPersistedReviewDossierDetails(record, resolvedProjectId);
                 writeHtmlDossier(record.result, {
                     outputPath: flags.output,
+                    open: shouldOpenHtmlDossier(flags),
                     sourceLabel: dossierDetails.sourceLabel,
                     storedReview: dossierDetails.storedReview,
                     approval: dossierDetails.approval,
@@ -1564,7 +1871,7 @@ export function registerIngestCommand(program) {
         const outputFormat = resolveIngestPresentationFormat(resolvedOpts.format);
         assertIngestPresentationMode(flags, outputFormat);
         const wantsHtmlDossier = shouldRenderHtmlDossier(outputFormat, flags.output);
-        const record = await waitForPersistedIngestJob(String(jobId));
+        const record = await waitForPersistedIngestJobWithLiveProgress(String(jobId), flags);
         const normalized = normalizeIngestJobRecord(record);
         if (!normalized) {
             throw new Error(`Persisted ingest job "${jobId}" could not be normalized.`);
@@ -1590,18 +1897,27 @@ export function registerIngestCommand(program) {
                 createdAt: normalized.result.persistedReview.createdAt,
             }
             : null;
-        renderIngestJobResult(normalized);
         if (wantsHtmlDossier) {
-            writeHtmlDossier(completedResult, {
+            const htmlDossier = writeHtmlDossier(completedResult, {
                 outputPath: flags.output,
+                open: shouldOpenHtmlDossier(flags),
                 sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? normalized.jobId,
                 storedReview: persistedReview,
             });
+            renderCompactIngestResultSummary(completedResult, {
+                sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? normalized.jobId,
+                persistedReview,
+                htmlDossier,
+            });
         }
         else if (flags.output) {
+            renderIngestJobResult(normalized);
             writeFileSync(flags.output, JSON.stringify(record.result, null, 2));
             success(`Results saved to ${flags.output}`);
         }
+        else {
+            renderIngestJobResult(normalized);
+        }
     });
     const resumeCmd = new Command('resume')
         .description('Resume a persisted geotechnical ingest job from completed checkpoints')
@@ -1661,18 +1977,27 @@ export function registerIngestCommand(program) {
                 createdAt: normalized.result.persistedReview.createdAt,
             }
             : null;
-        renderIngestJobResult(normalized);
         if (wantsHtmlDossier) {
-            writeHtmlDossier(completedResult, {
+            const htmlDossier = writeHtmlDossier(completedResult, {
                 outputPath: flags.output,
+                open: shouldOpenHtmlDossier(flags),
                 sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? normalized.jobId,
                 storedReview: persistedReview,
             });
+            renderCompactIngestResultSummary(completedResult, {
+                sourceLabel: completedResult.source.fileName ?? completedResult.source.filePath ?? normalized.jobId,
+                persistedReview,
+                htmlDossier,
+            });
         }
         else if (flags.output) {
+            renderIngestJobResult(normalized);
             writeFileSync(flags.output, JSON.stringify(result, null, 2));
             success(`Results saved to ${flags.output}`);
         }
+        else {
+            renderIngestJobResult(normalized);
+        }
     });
     const cancelCmd = new Command('cancel')
         .description('Cancel a persisted geotechnical ingest job')