@fairmint/captable-ai 0.1.25 → 0.1.26

package/dist/index.js

@@ -15483,6 +15483,344 @@ function buildClassificationTypes() {
 }
 var CLASSIFICATION_TYPES_LIST = buildClassificationTypes();
 
+// ../captable-ai-core/dist/extraction-readiness.js
+var STATUS_TO_CATEGORY = {
+  PENDING_UPLOAD: "pendingUpload",
+  NEW: "preclassification",
+  EXTRACTION: "preclassification",
+  CLASSIFICATION: "preclassification",
+  CLASSIFIED: "classified",
+  OCF_EXTRACTION: "extracting",
+  CREATION: "extracting",
+  VALIDATION: "validating",
+  FINALIZATION: "validating",
+  PROCESSED: "complete",
+  COMMITTED: "complete",
+  FAILED: "failed",
+  CANCELLED: "failed"
+};
+function categorizeDocumentStatus(status) {
+  if (typeof status !== "string")
+    return "unknown";
+  return STATUS_TO_CATEGORY[status.trim().toUpperCase()] ?? "unknown";
+}
+var extractionReadinessSummarySchema = external_exports.object({
+  total: external_exports.number().int().nonnegative().describe("Documents in scope."),
+  pendingUpload: external_exports.number().int().nonnegative().describe("Documents whose upload never completed (PENDING_UPLOAD)."),
+  preclassification: external_exports.number().int().nonnegative().describe("Documents still in OCR/classification (NEW, EXTRACTION, CLASSIFICATION)."),
+  classified: external_exports.number().int().nonnegative().describe("Documents classified and waiting for an extraction trigger."),
+  extracting: external_exports.number().int().nonnegative().describe("Documents in OCF extraction (OCF_EXTRACTION, CREATION)."),
+  validating: external_exports.number().int().nonnegative().describe("Documents waiting on portal validation (VALIDATION, FINALIZATION)."),
+  complete: external_exports.number().int().nonnegative().describe("Documents PROCESSED or COMMITTED."),
+  failed: external_exports.number().int().nonnegative().describe("Documents FAILED or CANCELLED."),
+  unknown: external_exports.number().int().nonnegative().describe("Documents with an unrecognized status."),
+  processing: external_exports.number().int().nonnegative().describe("Backward-compatible total of preclassification + extracting + validating + unknown.")
+});
+function summarizeExtractionReadiness(documents) {
+  const counts = {
+    pendingUpload: 0,
+    preclassification: 0,
+    classified: 0,
+    extracting: 0,
+    validating: 0,
+    complete: 0,
+    failed: 0,
+    unknown: 0
+  };
+  for (const document of documents) {
+    counts[categorizeDocumentStatus(document.status)] += 1;
+  }
+  return {
+    total: documents.length,
+    ...counts,
+    processing: counts.preclassification + counts.extracting + counts.validating + counts.unknown
+  };
+}
+function deriveExtractionReadinessPhase(summary) {
+  if (summary.total === 0)
+    return "empty";
+  if (summary.pendingUpload > 0)
+    return "awaiting_upload";
+  if (summary.preclassification > 0)
+    return "classifying";
+  if (summary.classified > 0)
+    return "ready_to_extract";
+  if (summary.extracting > 0 || summary.validating > 0 || summary.unknown > 0) {
+    return "in_progress";
+  }
+  if (summary.failed > 0)
+    return "failed";
+  return "complete";
+}
+var IMPORT_SESSION_CLOCK_SKEW_MS = 5e3;
+function documentsForImportSession(documents, sessionCreatedAt) {
+  if (typeof sessionCreatedAt !== "string")
+    return [];
+  const sessionMs = parseTimestampMs(sessionCreatedAt);
+  if (sessionMs === null)
+    return [];
+  const cutoffMs = sessionMs - IMPORT_SESSION_CLOCK_SKEW_MS;
+  return documents.filter((document) => {
+    if (typeof document.createdAt !== "string")
+      return false;
+    const createdMs = parseTimestampMs(document.createdAt);
+    return createdMs !== null && createdMs >= cutoffMs;
+  });
+}
+function importSessionScopeUnknown(documents) {
+  return documents.length > 0 && documents.every((document) => typeof document.createdAt !== "string" || parseTimestampMs(document.createdAt) === null);
+}
+var HAS_ZONE = /(?:Z|[+-]\d{2}(?::?\d{2})?)$/i;
+function parseTimestampMs(value) {
+  let normalized = value.trim().replace(" ", "T").replace(/([+-]\d{2})$/, "$1:00");
+  if (!HAS_ZONE.test(normalized))
+    normalized += "Z";
+  const parsed = Date.parse(normalized);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+var TRIGGER_EXTRACTION_MAX_IDS = 50;
+function idsInCategory(documents, category, predicate = () => true) {
+  return documents.flatMap((document) => categorizeDocumentStatus(document.status) === category && typeof document.s3AssetId === "string" && predicate(document) ? [document.s3AssetId] : []);
+}
+var isRetryableFailure = (document) => (document.status ?? "").trim().toUpperCase() === "FAILED";
+function sessionTriggerScope(documents) {
+  const eligible = documents.filter((document) => {
+    const category = categorizeDocumentStatus(document.status);
+    return category === "classified" || category === "failed" && isRetryableFailure(document);
+  });
+  const ids = eligible.flatMap((document) => typeof document.s3AssetId === "string" ? [document.s3AssetId] : []);
+  if (ids.length === 0 || ids.length !== eligible.length) {
+    return { kind: "unsafe", reason: "missing_ids" };
+  }
+  if (ids.length > TRIGGER_EXTRACTION_MAX_IDS)
+    return { kind: "unsafe", reason: "too_many_ids" };
+  const includesFailed = eligible.some((document) => categorizeDocumentStatus(document.status) === "failed");
+  return { kind: "explicit", ids, includesFailed };
+}
+var BACKGROUND_MONITORING_SUGGESTION = "Processing can take several minutes. If you can run subagents or background tasks, delegate a monitor that re-checks document status every 30-60 seconds for up to 30 minutes. When the phase changes it may run only the returned nextActions, exactly as scoped (for example, trigger extraction with the listed s3AssetIds once every document is classified; never widen the scope to the whole company). It stops and reports back when the import is ready for review, needs the user (failures, uploads, scope questions), or the time box ends. Otherwise, check again periodically and tell the user if the import is still processing after about 30 minutes.";
+function shouldSuggestBackgroundMonitoring(phase) {
+  switch (phase) {
+    case "classifying":
+    case "in_progress":
+      return true;
+    case "empty":
+    case "awaiting_upload":
+    case "ready_to_extract":
+    case "failed":
+    case "complete":
+      return false;
+    default: {
+      const unhandled = phase;
+      throw new Error(`Unhandled extraction readiness phase: ${String(unhandled)}`);
+    }
+  }
+}
+function reviewFailuresAction(documents) {
+  const statusSet = /* @__PURE__ */ new Set();
+  const ids = [];
+  for (const document of documents) {
+    if (categorizeDocumentStatus(document.status) !== "failed")
+      continue;
+    statusSet.add((document.status ?? "").trim().toUpperCase());
+    if (typeof document.s3AssetId === "string")
+      ids.push(document.s3AssetId);
+  }
+  const statuses = [...statusSet];
+  return {
+    id: "review_failures",
+    label: "Review failed documents",
+    required: true,
+    ...ids.length > 0 && { s3AssetIds: ids },
+    ...statuses.length === 1 && { statusFilter: statuses[0] }
+  };
+}
+function triggerOrResolve(trigger, scope) {
+  switch (scope.kind) {
+    case "explicit":
+      return {
+        ...trigger,
+        ...scope.includesFailed && {
+          label: "Start OCF extraction for classified documents and retry failed ones"
+        },
+        s3AssetIds: scope.ids
+      };
+    case "unsafe":
+      return {
+        id: "resolve_extraction_scope",
+        label: scope.reason === "too_many_ids" ? `This import has more classified documents than one scoped trigger accepts (${TRIGGER_EXTRACTION_MAX_IDS}), so extraction cannot be started safely for this import alone. Do not trigger extraction for the whole company on this import's behalf; ask the user how to proceed after reviewing the company's documents.` : "Some classified documents in this import have no document ID, so extraction cannot be scoped to this import. Review the company's documents, then check again.",
+        required: trigger.required
+      };
+    default: {
+      const unhandled = scope;
+      throw new Error(`Unhandled trigger scope: ${String(unhandled)}`);
+    }
+  }
+}
+function stallRecoveryActions(documents) {
+  const isStalled = (document) => document.health === "stalled";
+  const isStalledOcr = (document) => isStalled(document) && (document.status ?? "").trim().toUpperCase() === "EXTRACTION";
+  const stalledRestartable = [
+    ...idsInCategory(documents, "preclassification", isStalledOcr),
+    ...idsInCategory(documents, "extracting", isStalled)
+  ];
+  const actions = [];
+  if (stalledRestartable.length > TRIGGER_EXTRACTION_MAX_IDS) {
+    actions.push({
+      id: "resolve_extraction_scope",
+      label: `${stalledRestartable.length} documents in this import look stalled, more than one scoped restart accepts (${TRIGGER_EXTRACTION_MAX_IDS}). Do not restart extraction for the whole company on this import's behalf; ask the user how to proceed after reviewing the company's documents.`,
+      required: false
+    });
+  } else if (stalledRestartable.length > 0) {
+    actions.push({
+      id: "restart_extraction",
+      label: "Restart the stalled extraction",
+      required: false,
+      s3AssetIds: stalledRestartable
+    });
+  }
+  return actions;
+}
+function planImportStatus({ documents, sessionState, scopeUnknown = false }) {
+  const summary = summarizeExtractionReadiness(documents);
+  const phase = deriveExtractionReadinessPhase(summary);
+  if (scopeUnknown && phase === "empty") {
+    return {
+      phase,
+      state: "processing",
+      summary,
+      shouldComplete: false,
+      actions: [
+        {
+          id: "check_status",
+          label: "This server does not report document creation times, so this import's documents can't be identified. Do not re-upload; check the company's documents, or retry after the server is updated.",
+          required: true
+        }
+      ]
+    };
+  }
+  const upload = {
+    id: "upload_documents",
+    label: "Upload the documents",
+    required: true
+  };
+  const checkStatus = {
+    id: "check_status",
+    label: "Check import progress again",
+    required: true
+  };
+  const trigger = {
+    id: "trigger_extraction",
+    label: "Start OCF extraction for classified documents",
+    required: true
+  };
+  const triggerScope = sessionTriggerScope(documents);
+  switch (phase) {
+    case "empty":
+      return { phase, state: "ready_to_import", summary, shouldComplete: false, actions: [upload] };
+    case "awaiting_upload":
+      return {
+        phase,
+        state: "ready_to_import",
+        summary,
+        shouldComplete: false,
+        actions: [
+          {
+            ...upload,
+            label: "Re-upload (or delete) the documents that did not finish uploading"
+          }
+        ]
+      };
+    case "classifying":
+      return {
+        phase,
+        state: "processing",
+        summary,
+        shouldComplete: false,
+        actions: [
+          { ...checkStatus, label: "Wait for classification, then check again" },
+          ...stallRecoveryActions(documents)
+        ]
+      };
+    case "ready_to_extract":
+      return {
+        phase,
+        state: "ready_to_import",
+        summary,
+        shouldComplete: false,
+        actions: [
+          triggerOrResolve(trigger, triggerScope),
+          // CLASSIFIED documents take priority over in-flight ones in the
+          // phase, so a stall elsewhere in the import would otherwise get no
+          // recovery action: triggering only queues CLASSIFIED/FAILED docs.
+          ...stallRecoveryActions(documents)
+        ]
+      };
+    case "in_progress":
+      return {
+        phase,
+        state: "processing",
+        summary,
+        shouldComplete: false,
+        actions: [
+          checkStatus,
+          ...stallRecoveryActions(documents),
+          // Surface failures now rather than after the last in-flight document
+          // settles; optional because processing is still moving.
+          ...summary.failed > 0 ? [{ ...reviewFailuresAction(documents), required: false }] : []
+        ]
+      };
+    case "failed":
+      return {
+        phase,
+        state: "blocked",
+        summary,
+        shouldComplete: false,
+        actions: [reviewFailuresAction(documents)]
+      };
+    case "complete":
+      return {
+        phase,
+        state: "needs_review",
+        summary,
+        shouldComplete: sessionState !== "completed",
+        actions: [
+          { id: "review_drafts", label: "Review extracted cap table drafts", required: true },
+          { id: "preview_commit", label: "Preview the first commit", required: true },
+          { id: "confirm_commit", label: "Commit reviewed drafts", required: true }
+        ]
+      };
+    default: {
+      const unhandled = phase;
+      throw new Error(`Unhandled extraction readiness phase: ${String(unhandled)}`);
+    }
+  }
+}
+var EXTRACTION_NOT_READY_REASONS = [
+  "pending_upload",
+  "classification_in_progress"
+];
+var TRIGGER_EXTRACTION_OUTCOMES = [
+  "queued",
+  "partially_queued",
+  "queue_failed",
+  "not_ready",
+  "no_eligible_documents"
+];
+function resolveTriggerExtractionOutcome(result) {
+  const declared = TRIGGER_EXTRACTION_OUTCOMES.find((value) => value === result.outcome);
+  if (declared)
+    return declared;
+  const queued = result.queuedCount ?? 0;
+  const failed = result.failedCount ?? 0;
+  if (queued > 0)
+    return failed > 0 ? "partially_queued" : "queued";
+  if (failed > 0)
+    return "queue_failed";
+  if (result.notReadyDocuments?.some((d) => d.blocking === true))
+    return "not_ready";
+  return "no_eligible_documents";
+}
+
 // ../captable-ai-core/dist/documents.js
 var documentPrepareFileSchema = external_exports.object({
   name: external_exports.string().min(1).describe("Original filename."),
@@ -15563,16 +15901,31 @@ var documentContextResultSchema = external_exports.object({
   existing: external_exports.record(external_exports.string(), external_exports.unknown()).describe("Compact existing portal context. Empty when includeExisting=false.")
 });
 var triggerExtractionInputSchema = external_exports.object({
-  s3AssetIds: external_exports.array(external_exports.string().uuid()).min(1).max(50).optional().describe("Optional filter to specific document IDs (1-50).")
+  s3AssetIds: external_exports.array(external_exports.string().uuid()).min(1).max(TRIGGER_EXTRACTION_MAX_IDS).optional().describe(`Optional filter to specific document IDs (1-${TRIGGER_EXTRACTION_MAX_IDS}).`)
 });
 var triggerExtractionDocSchema = external_exports.object({
   s3AssetId: external_exports.string().describe("S3 asset ID."),
   date: external_exports.string().nullable().describe("Document date.")
 });
+var triggerExtractionNotReadyDocSchema = external_exports.object({
+  s3AssetId: external_exports.string().describe("S3 asset ID."),
+  status: external_exports.string().describe("Current document status."),
+  reason: external_exports.enum(EXTRACTION_NOT_READY_REASONS).describe("pending_upload: upload never completed, re-upload or delete it. classification_in_progress: OCR/classification still running, wait and retry."),
+  blocking: external_exports.boolean().describe("True when this document prevented the batch from being queued.")
+});
+var triggerExtractionSkippedDocSchema = external_exports.object({
+  s3AssetId: external_exports.string().describe("S3 asset ID."),
+  status: external_exports.string().describe("Current document status (already extracting, validated, etc.).")
+});
 var triggerExtractionResultSchema = external_exports.object({
+  outcome: external_exports.enum(TRIGGER_EXTRACTION_OUTCOMES).describe("queued | partially_queued | queue_failed | not_ready (nothing queued because in-scope documents are still classifying or uploading) | no_eligible_documents."),
   queuedCount: external_exports.number().describe("Number of documents queued for extraction."),
   failedCount: external_exports.number().describe("Number of documents that failed to queue."),
-  documents: external_exports.array(triggerExtractionDocSchema).describe("Documents processed.")
+  documents: external_exports.array(triggerExtractionDocSchema).describe("Documents queued, in queue order."),
+  notReadyCount: external_exports.number().int().nonnegative().describe("Number of in-scope documents not ready for extraction."),
+  notReadyDocuments: external_exports.array(triggerExtractionNotReadyDocSchema).describe("In-scope documents not ready for extraction."),
+  skippedDocuments: external_exports.array(triggerExtractionSkippedDocSchema).describe("Explicitly requested documents that are not in an extractable status."),
+  missingIds: external_exports.array(external_exports.string()).describe("Explicitly requested document IDs not found in this portal.")
 });
 var cancelExtractionInputSchema = external_exports.object({
   documentId: external_exports.string().uuid().describe("The s3_asset_id of the document to cancel.")
@@ -15615,6 +15968,7 @@ var DOCUMENT_HEALTH_VALUES = [
 var documentProcessingStatusItemSchema = external_exports.object({
   s3AssetId: external_exports.string().describe("S3 asset / document ID."),
   status: external_exports.string().describe("Document processing status."),
+  createdAt: external_exports.string().nullable().optional().describe("Immutable document creation timestamp; absent on older servers."),
   lastActivityAt: external_exports.string().nullable().describe("Last backend activity timestamp (updated_at / heartbeat); null if unknown."),
   queuePosition: external_exports.number().int().min(0).nullable().describe("0 = at the head (processing); >0 = waiting behind others; null = not in pipeline."),
   health: external_exports.enum(DOCUMENT_HEALTH_VALUES).describe("Derived health from backend heartbeat + queue position.")
@@ -17547,7 +17901,7 @@ var COMMAND_REGISTRY = [
   {
     name: "import status",
     group: "onboarding",
-    description: "Show import processing progress and the next existing-pipeline action.",
+    description: "Show import progress by phase (uploading, classifying, ready to extract, extracting, validating) and the next action. Classified documents are actionable even while others validate; unfinished uploads need a re-upload, not more polling.",
     usage: "captable-ai import status <session-id> [--json]",
     requiresAuth: true,
     requiresPortal: false
@@ -17932,7 +18286,7 @@ var COMMAND_REGISTRY = [
   {
     name: "documents trigger-extraction",
     group: "captable",
-    description: "Trigger OCF extraction for classified documents. Sends them to the extraction queue for processing. Optionally filter to specific document IDs.",
+    description: "Trigger OCF extraction for classified documents in chronological order. Optionally filter to specific document IDs. Queues nothing (outcome not_ready, exit 5) while a document in scope is still classifying or a requested document never finished uploading; wait or re-upload, then retry. Only queued batches are tracked as jobs.",
     usage: "captable-ai documents trigger-extraction [--s3-asset-ids ID1,ID2,...] [--json]",
     requiresAuth: true,
     requiresPortal: true,
@@ -18824,11 +19178,11 @@ async function runCommit(args, rawArgv) {
     process.exit(0);
   }
   validateFlags(args, { flags: ["objects"], booleans: ["all", "dry-run"] });
-  const USAGE = "captable-ai commit --dry-run [--objects id1,id2,...] [--json]\ncaptable-ai commit (--objects id1,id2,... | --all) [--json]";
+  const USAGE2 = "captable-ai commit --dry-run [--objects id1,id2,...] [--json]\ncaptable-ai commit (--objects id1,id2,... | --all) [--json]";
   if (args.positional.length > 0) {
     exitWithUsage(
       `Unexpected argument: ${args.positional[0]}. This command takes no positional arguments.`,
-      USAGE
+      USAGE2
     );
   }
   const dryRun = hasFlag(args, "dry-run");
@@ -18837,10 +19191,10 @@ async function runCommit(args, rawArgv) {
   const objectIds = parseObjectIdsList(objectIdsRaw);
   const hasExplicitObjectIds = hasObjectIds(objectIdsRaw, objectIds);
   if (objectIdsRaw !== void 0 && !hasExplicitObjectIds) {
-    exitWithUsage("The --objects flag must include at least one object ID.", USAGE);
+    exitWithUsage("The --objects flag must include at least one object ID.", USAGE2);
   }
   if (all && objectIds) {
-    exitWithUsage("Specify either --objects or --all, not both.", USAGE);
+    exitWithUsage("Specify either --objects or --all, not both.", USAGE2);
   }
   if (dryRun) {
     const portalId2 = await getActivePortalId();
@@ -18867,7 +19221,7 @@ async function runCommit(args, rawArgv) {
     { objectIdsLabel: "--objects id1,id2,...", allDraftsLabel: "--all" }
   );
   if (!selection.ok) {
-    exitWithUsage(`${selection.message} Preview first with --dry-run.`, USAGE);
+    exitWithUsage(`${selection.message} Preview first with --dry-run.`, USAGE2);
   }
   const portalId = await getActivePortalId();
   if (!isJsonMode()) {
@@ -19715,81 +20069,174 @@ async function atomicWriteJobs(content) {
 }
 
 // src/commands/documents-trigger-extraction.ts
+var USAGE = "Usage: captable-ai documents trigger-extraction [--s3-asset-ids ID1,ID2,...] [--json]";
+var HELP = `documents trigger-extraction \u2014 Trigger OCF extraction
+
+${USAGE}
+
+Queues CLASSIFIED (and previously FAILED) documents in chronological order.
+Nothing is queued while a document in scope is still being classified, or an
+explicitly requested document never finished uploading; the command then exits
+with code 5 (outcome not_ready) and lists those documents. Wait for classification
+(captable-ai documents processing-status) or re-upload, then retry.
+`;
+function normalize(data) {
+  const d = data ?? {};
+  return { ...d, outcome: resolveTriggerExtractionOutcome(d) };
+}
 async function runDocumentsTriggerExtraction(args, rawArgv) {
   if (rawArgv.includes("--help") || rawArgv.includes("-h")) {
-    process.stdout.write(
-      "documents trigger-extraction \u2014 Trigger OCF extraction\n\nUsage: captable-ai documents trigger-extraction [--s3-asset-ids ID1,ID2,...] [--json]\n"
-    );
+    process.stdout.write(HELP);
     process.exit(0);
   }
   validateFlags(args, { flags: ["s3-asset-ids"], booleans: [] });
   if (args.positional.length > 0) {
     exitWithUsage(
       "Unexpected positional argument(s). Use --s3-asset-ids to filter specific documents.",
-      "Usage: captable-ai documents trigger-extraction [--s3-asset-ids ID1,ID2,...] [--json]"
+      USAGE
     );
   }
   const portalId = await getActivePortalId();
   const body = {};
   const rawIds = getFlagValue(args, "s3-asset-ids");
-  if (rawIds) {
-    const ids = rawIds.split(",").map((id) => id.trim()).filter(Boolean);
-    if (ids.length > 0) body.s3AssetIds = ids;
+  const requestedIds = rawIds === void 0 ? [] : rawIds.split(",").map((id) => id.trim()).filter(Boolean);
+  if (rawIds !== void 0 && requestedIds.length === 0) {
+    exitWithUsage("--s3-asset-ids needs at least one document ID.", USAGE);
   }
-  const res = await apiRequest(
-    `/${portalId}/documents/trigger-extraction`,
-    {
-      method: "POST",
-      body
+  if (requestedIds.length > 0) body.s3AssetIds = requestedIds;
+  const retryCommand = "captable-ai documents trigger-extraction" + (requestedIds.length > 0 ? ` --s3-asset-ids ${requestedIds.join(",")}` : "");
+  const res = await apiRequest(`/${portalId}/documents/trigger-extraction`, {
+    method: "POST",
+    body
+  });
+  const d = normalize(res.data);
+  const queuedIds = d.documents?.map((doc) => doc.s3AssetId) ?? [];
+  const notReady = d.notReadyDocuments ?? [];
+  const blocking = notReady.filter((doc) => doc.blocking);
+  let jobId = null;
+  let trackerFailed = false;
+  if (queuedIds.length > 0) {
+    jobId = generateJobId();
+    try {
+      await appendJob({
+        id: jobId,
+        kind: "extraction",
+        portalId,
+        s3AssetIds: queuedIds,
+        submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        status: "submitted",
+        lastCheckedAt: null,
+        completedAt: null,
+        result: null
+      });
+    } catch (trackErr) {
+      trackerFailed = true;
+      jobId = null;
+      printWarning(
+        `Job tracker write failed: ${trackErr instanceof Error ? trackErr.message : String(trackErr)}`
+      );
     }
-  );
-  const d = res.data ?? { queuedCount: 0, failedCount: 0, documents: [] };
-  const jobId = generateJobId();
-  const s3AssetIds = d.documents?.map((doc) => doc.s3AssetId) ?? [];
-  let tracked = true;
-  try {
-    await appendJob({
-      id: jobId,
-      kind: "extraction",
-      portalId,
-      s3AssetIds,
-      submittedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      status: d.queuedCount > 0 ? "submitted" : "failed",
-      lastCheckedAt: null,
-      completedAt: d.queuedCount === 0 ? (/* @__PURE__ */ new Date()).toISOString() : null,
-      result: null
-    });
-  } catch (trackErr) {
-    tracked = false;
-    printWarning(
-      `Job tracker write failed: ${trackErr instanceof Error ? trackErr.message : String(trackErr)}`
-    );
   }
   if (isJsonMode()) {
     printJson({
-      data: res.data,
-      ...tracked && {
+      data: { ...res.data, outcome: d.outcome },
+      ...jobId && {
         jobId,
-        hint: `Extraction takes 5-30+ min. Check progress: captable-ai jobs get ${jobId}`
+        hint: `Extraction takes 5-30+ min. Check progress: captable-ai jobs get ${jobId}`,
+        monitoringHint: BACKGROUND_MONITORING_SUGGESTION
       },
-      ...!tracked && { trackerWarning: "Local job tracking failed." }
+      ...trackerFailed && { trackerWarning: "Local job tracking failed." },
+      ...d.outcome === "not_ready" && {
+        hint: "Nothing was queued. Wait for classification to finish (or re-upload unfinished uploads), then retry."
+      }
     });
+    if (d.outcome === "not_ready") process.exitCode = EXIT.CONFLICT;
+    if (d.outcome === "queue_failed" || d.outcome === "partially_queued") {
+      process.exitCode = EXIT.SERVER_ERROR;
+    }
+    flagMissingIds(d.missingIds);
     return;
   }
-  if (d.queuedCount === 0 && d.failedCount > 0) {
-    exitWithError(
-      `All ${d.failedCount} document(s) failed to queue for extraction.`,
-      "EXTRACTION_QUEUE_FAILED",
-      void 0,
-      EXIT.SERVER_ERROR
-    );
+  switch (d.outcome) {
+    case "not_ready": {
+      const uploads = blocking.filter((doc) => doc.reason === "pending_upload");
+      const classifying = blocking.filter((doc) => doc.reason === "classification_in_progress");
+      const details = blocking.map((doc) => ({
+        path: doc.s3AssetId,
+        message: `${doc.status}: ${doc.reason}`
+      }));
+      const parts = [];
+      if (classifying.length > 0) {
+        parts.push(
+          `${classifying.length} document(s) are still being classified; wait and retry (captable-ai documents processing-status). If one stays stuck, retry with --s3-asset-ids listing only the documents you intend to extract`
+        );
+      }
+      if (uploads.length > 0) {
+        parts.push(
+          `${uploads.length} requested document(s) never finished uploading; re-upload or delete them`
+        );
+      }
+      exitWithError(
+        `No documents were queued. ${parts.join(". ")}.`,
+        "EXTRACTION_NOT_READY",
+        details,
+        EXIT.CONFLICT
+      );
+      break;
+    }
+    case "queue_failed":
+      exitWithError(
+        `All ${d.failedCount ?? 0} document(s) failed to queue for extraction. Retry shortly: ${retryCommand}`,
+        "EXTRACTION_QUEUE_FAILED",
+        void 0,
+        EXIT.SERVER_ERROR
+      );
+      break;
+    case "no_eligible_documents":
+      printLine("No CLASSIFIED or FAILED documents in scope; nothing was queued.");
+      break;
+    case "queued":
+    case "partially_queued":
+      printSuccess(
+        `Queued ${d.queuedCount ?? queuedIds.length} document(s) for extraction${(d.failedCount ?? 0) > 0 ? ` (${d.failedCount} failed to queue)` : ""}.`
+      );
+      if (jobId) {
+        printSuccess(`Job tracked: ${jobId}. Check progress: captable-ai jobs get ${jobId}`);
+        printLine(`Tip: ${BACKGROUND_MONITORING_SUGGESTION}`);
+      }
+      if (d.outcome === "partially_queued") {
+        printWarning(
+          `${d.failedCount ?? 0} document(s) failed to queue and are still waiting for extraction. Re-run ${retryCommand} to queue them.`
+        );
+        process.exitCode = EXIT.SERVER_ERROR;
+      }
+      break;
+    default: {
+      const unhandled = d.outcome;
+      throw new Error(`Unhandled trigger outcome: ${String(unhandled)}`);
+    }
   }
-  printSuccess(
-    `Queued ${d.queuedCount} document(s) for extraction${d.failedCount > 0 ? ` (${d.failedCount} failed to queue)` : ""}.`
+  const nonBlockingUploads = notReady.filter(
+    (doc) => !doc.blocking && doc.reason === "pending_upload"
   );
-  if (tracked) {
-    printSuccess(`Job tracked: ${jobId}. Check progress: captable-ai jobs get ${jobId}`);
+  if (nonBlockingUploads.length > 0) {
+    printWarning(
+      `${nonBlockingUploads.length} document(s) never finished uploading and were not queued. Re-upload or delete them.`
+    );
+  }
+  const skipped = d.skippedDocuments ?? [];
+  if (skipped.length > 0) {
+    printWarning(
+      `Not queued (already in progress or complete): ${skipped.map((doc) => `${doc.s3AssetId} (${doc.status})`).join(", ")}.`
+    );
+  }
+  if ((d.missingIds?.length ?? 0) > 0) {
+    printWarning(`Not found in this company: ${d.missingIds?.join(", ")}`);
   }
+  flagMissingIds(d.missingIds);
+}
+function flagMissingIds(missingIds) {
+  if ((missingIds?.length ?? 0) > 0 && !process.exitCode) process.exitCode = EXIT.NOT_FOUND;
 }
 
 // src/commands/documents-upload.ts
@@ -21475,22 +21922,22 @@ async function runObjectsRevert(args, rawArgv) {
   const objectIdsRaw = getFlagValue(args, "objects");
   const objectIdsFromFlag = parseObjectIdsList(objectIdsRaw);
   const hasExplicitObjectIds = hasObjectIds(objectIdsRaw, objectIdsFromFlag);
-  const USAGE = "captable-ai objects revert --dry-run [<object-id> | --objects id1,id2,... | --all] [--json]\ncaptable-ai objects revert (<object-id> | --objects id1,id2,... | --all) [--yes] [--json]";
+  const USAGE2 = "captable-ai objects revert --dry-run [<object-id> | --objects id1,id2,... | --all] [--json]\ncaptable-ai objects revert (<object-id> | --objects id1,id2,... | --all) [--yes] [--json]";
   if (args.positional.length > 1) {
     exitWithUsage(
       `Too many arguments: expected one object ID, got ${args.positional.length}.`,
-      USAGE
+      USAGE2
     );
   }
   if (objectIdRaw !== void 0 && !objectId) {
-    exitWithUsage("Object ID must be a non-empty string.", USAGE);
+    exitWithUsage("Object ID must be a non-empty string.", USAGE2);
   }
   if (objectIdsRaw !== void 0 && !hasExplicitObjectIds) {
-    exitWithUsage("The --objects flag must include at least one object ID.", USAGE);
+    exitWithUsage("The --objects flag must include at least one object ID.", USAGE2);
   }
   const selectionSources = [Boolean(objectId), Boolean(objectIdsFromFlag), all].filter(Boolean);
   if (selectionSources.length > 1) {
-    exitWithUsage("Specify only one of an object ID, --objects, or --all.", USAGE);
+    exitWithUsage("Specify only one of an object ID, --objects, or --all.", USAGE2);
   }
   const objectIds = objectId ? [objectId] : objectIdsFromFlag;
   if (dryRun) {
@@ -21520,7 +21967,7 @@ async function runObjectsRevert(args, rawArgv) {
     { objectIdsLabel: "<object-id> or --objects id1,id2,...", allDraftsLabel: "--all" }
   );
   if (!selection.ok) {
-    exitWithUsage(`${selection.message} Preview first with --dry-run.`, USAGE);
+    exitWithUsage(`${selection.message} Preview first with --dry-run.`, USAGE2);
   }
   const portalId = await getActivePortalId();
   if (selection.allDrafts) {
@@ -22160,28 +22607,45 @@ async function runImportStart(args) {
   printLine("Upload documents: captable-ai documents upload <file...>");
   printLine(`Check progress: captable-ai import status ${session.id}`);
 }
-var TERMINAL_DOCUMENT_STATUSES = /* @__PURE__ */ new Set(["PROCESSED", "COMMITTED", "FAILED", "CANCELLED"]);
-function documentsForImportSession(documents, sessionCreatedAt) {
-  if (typeof sessionCreatedAt !== "string" || sessionCreatedAt.length === 0) return [];
-  return documents.filter(
-    (document) => typeof document.lastActivityAt === "string" && document.lastActivityAt >= sessionCreatedAt
-  );
-}
-function summarizeImportDocuments(documents) {
-  const statuses = documents.map((document) => (document.status ?? "").toUpperCase());
-  const failed = statuses.filter((status) => ["FAILED", "CANCELLED"].includes(status)).length;
-  const classified = statuses.filter((status) => status === "CLASSIFIED").length;
-  const pendingUpload = statuses.filter((status) => status === "PENDING_UPLOAD").length;
-  const processing = statuses.filter(
-    (status) => status !== "" && !TERMINAL_DOCUMENT_STATUSES.has(status) && status !== "CLASSIFIED" && status !== "PENDING_UPLOAD"
-  ).length;
+function scopeFlag(ids) {
+  return ids && ids.length > 0 ? ` --s3-asset-ids ${ids.join(",")}` : "";
+}
+function importStatusCommand(action, sessionId) {
+  const command = (() => {
+    switch (action.id) {
+      case "upload_documents":
+        return "captable-ai documents upload <file...>";
+      case "trigger_extraction":
+        return `captable-ai documents trigger-extraction${scopeFlag(action.s3AssetIds)}`;
+      case "check_status":
+        return `captable-ai import status ${sessionId}`;
+      case "restart_extraction":
+        return `captable-ai documents restart-extraction${scopeFlag(action.s3AssetIds)}`;
+      case "retrigger_validation":
+        return "captable-ai retrigger-validation";
+      case "resolve_extraction_scope":
+        return "captable-ai documents list";
+      case "review_failures":
+        return action.statusFilter ? `captable-ai documents list --status ${action.statusFilter}` : "captable-ai documents list";
+      case "review_drafts":
+        return "captable-ai objects list --status draft --all";
+      case "preview_commit":
+        return "captable-ai commit --dry-run";
+      case "confirm_commit":
+        return "captable-ai commit --all";
+      default: {
+        const unhandled = action.id;
+        throw new Error(`Unhandled import status action: ${String(unhandled)}`);
+      }
+    }
+  })();
+  const id = action.id === "upload_documents" ? "upload_cli" : action.id;
   return {
-    total: documents.length,
-    processing,
-    classified,
-    pendingUpload,
-    failed,
-    complete: documents.length - failed - processing - classified - pendingUpload
+    id,
+    label: action.label,
+    required: action.required,
+    command,
+    ...action.id === "review_failures" && action.s3AssetIds && { s3AssetIds: action.s3AssetIds }
   };
 }
 async function runImportStatus(args) {
@@ -22196,13 +22660,15 @@ async function runImportStatus(args) {
   const response = await apiRequest(
     `/import-sessions/${encodeURIComponent(sessionId)}/status`
   );
-  const documents = documentsForImportSession(
-    response.data?.processing?.documents ?? [],
-    response.data?.session?.createdAt
-  );
-  const summary = summarizeImportDocuments(documents);
-  const sessionState = response.data?.session?.state;
-  if (documents.length > 0 && summary.processing === 0 && summary.classified === 0 && summary.pendingUpload === 0 && summary.failed === 0 && sessionState !== "completed") {
+  const portalDocuments = response.data?.processing?.documents ?? [];
+  const documents = documentsForImportSession(portalDocuments, response.data?.session?.createdAt);
+  const plan = planImportStatus({
+    documents,
+    sessionState: response.data?.session?.state,
+    scopeUnknown: importSessionScopeUnknown(portalDocuments)
+  });
+  const { summary } = plan;
+  if (plan.shouldComplete) {
     const completed = await apiRequest(
       `/import-sessions/${encodeURIComponent(sessionId)}/complete`,
       {
@@ -22214,56 +22680,15 @@ async function runImportStatus(args) {
       response.data.session = { ...response.data.session, ...completed.data.session };
     }
   }
-  const state = documents.length === 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.processing > 0 ? ONBOARDING_STATES.PROCESSING : summary.classified > 0 || summary.pendingUpload > 0 ? ONBOARDING_STATES.READY_TO_IMPORT : summary.failed > 0 ? ONBOARDING_STATES.BLOCKED : ONBOARDING_STATES.NEEDS_REVIEW;
-  const nextActions = documents.length === 0 || summary.pendingUpload > 0 ? [
-    nextAction(
-      "upload_cli",
-      "Upload local documents directly to S3",
-      "captable-ai documents upload <file...>"
-    ),
-    ...summary.classified > 0 ? [
-      nextAction(
-        "trigger_extraction",
-        "Start OCF extraction for classified documents",
-        "captable-ai documents trigger-extraction"
-      )
-    ] : []
-  ] : summary.classified > 0 ? [
-    nextAction(
-      "trigger_extraction",
-      "Start OCF extraction for classified documents",
-      "captable-ai documents trigger-extraction"
-    )
-  ] : summary.processing > 0 ? [
-    nextAction(
-      "check_status",
-      "Check import progress again",
-      `captable-ai import status ${sessionId}`
-    )
-  ] : summary.failed > 0 ? [
-    nextAction(
-      "review_failures",
-      "Review failed documents",
-      "captable-ai documents list --status FAILED"
-    )
-  ] : [
-    nextAction(
-      "review_drafts",
-      "Review extracted drafts",
-      "captable-ai objects list --status draft --all"
-    ),
-    nextAction(
-      "preview_commit",
-      "Preview the first commit",
-      "captable-ai commit --dry-run"
-    ),
-    nextAction("confirm_commit", "Commit reviewed drafts", "captable-ai commit --all")
-  ];
+  const nextActions = plan.actions.map((action) => importStatusCommand(action, sessionId));
+  const suggestMonitoring = shouldSuggestBackgroundMonitoring(plan.phase);
   const data = {
     ...response.data,
-    state,
+    state: plan.state,
+    phase: plan.phase,
     summary,
-    nextActions
+    nextActions,
+    ...suggestMonitoring && { monitoringHint: BACKGROUND_MONITORING_SUGGESTION }
   };
   if (isJsonMode()) {
     printJson({ data });
@@ -22272,14 +22697,33 @@ async function runImportStatus(args) {
   printKeyValue([
     ["Session", sessionId],
     ["State", data.state],
+    ["Phase", plan.phase],
     ["Documents", summary.total],
+    ["Pending upload", summary.pendingUpload],
+    ["Classifying", summary.preclassification],
     ["Classified", summary.classified],
-    ["Processing", summary.processing],
+    ["Extracting", summary.extracting],
+    ["Validating", summary.validating],
     ["Complete", summary.complete],
     ["Failed", summary.failed]
   ]);
+  if (plan.phase === "awaiting_upload") {
+    printLine(
+      "  Some uploads never finished. Re-upload them; checking status again will not complete them."
+    );
+  }
   for (const action of nextActions) {
-    printLine(`  Next: ${String(action.command)}`);
+    printLine(`  Next: ${action.command}`);
+    if (action.id === "resolve_extraction_scope") printLine(`    Note: ${action.label}`);
+    if (action.id === "check_status" && plan.phase === "empty") {
+      printLine(`    Note: ${action.label}`);
+    }
+    if (action.id === "review_failures" && action.s3AssetIds) {
+      printLine(`    Documents: ${action.s3AssetIds.join(", ")}`);
+    }
+  }
+  if (suggestMonitoring) {
+    printLine(`  Tip: ${BACKGROUND_MONITORING_SUGGESTION}`);
   }
 }
 
@@ -23107,7 +23551,7 @@ Onboarding:
   onboarding status         Show the next setup/import action (works with zero companies)
   onboarding setup          Create the first production workspace
   import start              Start or reuse a document import session
-  import status <id>        Check import processing via existing document APIs
+  import status <id>        Show import phase and the next action (upload, wait, extract, review)
 
 Cap Table (read):
   summary                   Full cap table snapshot (capitalization, stakeholders, metrics)
@@ -23164,6 +23608,7 @@ Agent Logs (Fairmint super-admin only):
 
 Extraction Pipeline:
   documents trigger-extraction  Trigger OCF extraction for classified documents
+                                 Queues nothing while documents are still classifying
                                  Filter: --s3-asset-ids ID1,ID2,...
   documents cancel-extraction <s3AssetId>  Cancel a stuck extraction
   documents restart-extraction  Atomically restart stuck extractions (cancel + re-enqueue)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairmint/captable-ai",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "description": "Agent-native CLI for Captable AI — manage companies, upload documents, run OCF extraction, and commit cap tables from the terminal.",
   "keywords": [
     "captable",