fullstackgtm 0.50.0 → 0.51.0

package/src/cli/plans.ts

@@ -11,7 +11,7 @@ import { formatPatchPlanRun, patchPlanToMarkdown } from "../format.ts";
 import { mergeSnapshots } from "../merge.ts";
 import { verifyApprovalDigests } from "../integrity.ts";
 import { buildAuditLog, verifyAuditLog } from "../auditLog.ts";
-import { createFilePlanStore } from "../planStore.ts";
+import { createFilePlanStore, type StoredPlan } from "../planStore.ts";
 import { ENRICH_CONFIG_FILE_NAME, loadEnrichConfig, type EnrichConfig } from "../enrich.ts";
 import { loadMeter, recordConsumption, remaining } from "../acquireMeter.ts";
 import { progressReporter, reportCounts } from "../runReport.ts";
@@ -20,7 +20,7 @@ import { APPLY_STAGES, composeListeners, createProgressEmitter } from "../progre
 import type { ValueSuggestion } from "../suggest.ts";
 import type { CanonicalGtmSnapshot, CreateRecordPayload, PatchOperation, PatchPlan, PatchPlanRun } from "../types.ts";
 import { connectorFor, isOptionValue, numericOption, option, repeatedOption, selectedRules } from "./shared.ts";
-import { colorEnabled, createProgressRenderer, paint, planStatusWord, stylizePlanMarkdown, table, truncateToWidth } from "./ui.ts";
+import { box, colorEnabled, createProgressRenderer, createStatusLine, formatDuration, paint, planStatusWord, stylizePlanMarkdown, table, truncateToWidth } from "./ui.ts";
 import { unknownSubcommandError } from "./suggest.ts";
 
 
@@ -34,6 +34,115 @@ function parseValueOverrides(args: string[]) {
   return valueOverrides;
 }
 
+function recordHeadline(operation: PatchOperation): { title: string; subtitle?: string; company?: string } {
+  const after = operation.afterValue && typeof operation.afterValue === "object" && !Array.isArray(operation.afterValue)
+    ? operation.afterValue as Record<string, unknown> : {};
+  const properties = after.properties && typeof after.properties === "object" && !Array.isArray(after.properties)
+    ? after.properties as Record<string, unknown> : {};
+  const first = typeof properties.firstname === "string" ? properties.firstname : "";
+  const last = typeof properties.lastname === "string" ? properties.lastname : "";
+  const company = typeof properties.company === "string" ? properties.company
+    : typeof after.associateCompanyName === "string" ? after.associateCompanyName : undefined;
+  const title = [first, last].filter(Boolean).join(" ") || company || operation.objectId || operation.id;
+  const role = typeof properties.jobtitle === "string" ? properties.jobtitle : undefined;
+  return { title, ...(role ? { subtitle: role } : {}), ...(company ? { company } : {}) };
+}
+
+function planEffect(stored: StoredPlan): string {
+  const total = stored.plan.operations.length;
+  const approved = stored.approvedOperationIds.length;
+  if (stored.status === "applied") {
+    const results = stored.runs.at(-1)?.results ?? [];
+    const applied = results.filter((result) => result.status === "applied").length;
+    const skipped = results.filter((result) => result.status === "skipped").length;
+    return `Completed ${applied} operation${applied === 1 ? "" : "s"}${skipped ? `; ${skipped} skipped` : ""}. No further writes will run.`;
+  }
+  if (stored.status === "approved") return `Apply will execute ${approved} selected operation${approved === 1 ? "" : "s"}; ${total - approved} will not run.`;
+  if (stored.status === "rejected") return "Rejected. No provider writes can run.";
+  return `No provider writes can run until operations are approved (0 of ${total} selected).`;
+}
+
+function printPlanCards(stored: StoredPlan, hostedUrl?: string) {
+  const p = paint(colorEnabled(process.stdout));
+  const total = stored.plan.operations.length;
+  const approved = new Set(stored.approvedOperationIds);
+  const width = Math.max(56, Math.min(100, (process.stdout.columns ?? 100) - 4));
+  const fit = (value: string) => truncateToWidth(value, width);
+  const summary = [
+    fit(stored.plan.title),
+    `Status     ${stored.status.toUpperCase().replaceAll("_", " ")}`,
+    `Selection  ${approved.size} of ${total} operation${total === 1 ? "" : "s"} approved`,
+    `Runs       ${stored.runs.length}`,
+    fit(`Effect     ${planEffect(stored)}`),
+  ];
+  console.log(box(summary, p, "Plan").join("\n"));
+  if (hostedUrl) console.log(`Hosted: ${hostedUrl}`);
+  console.log("\nOperations");
+  let operationIndex = 0;
+  const latestResults = new Map((stored.runs.at(-1)?.results ?? []).map((result) => [result.operationId, result.status]));
+  for (const operation of stored.plan.operations) {
+    const selected = approved.has(operation.id);
+    const resultStatus = latestResults.get(operation.id);
+    const headline = recordHeadline(operation);
+    const action = operation.operation === "create_record"
+      ? `Create ${operation.objectType}${headline.company ? ` and resolve/link ${headline.company}` : ""}`
+      : `${operation.operation.replaceAll("_", " ")} ${operation.objectType}`;
+    const lines = [
+      fit(headline.title),
+      ...(headline.subtitle || headline.company
+        ? [fit([headline.subtitle, headline.company].filter(Boolean).join(" · "))]
+        : []),
+      fit(`Action     ${action}`),
+      `Operation  ${operation.id}`,
+    ];
+    if (operationIndex++ > 0) console.log("");
+    const state = resultStatus === "applied" ? "✓ APPLIED"
+      : resultStatus && selected ? `! ${resultStatus.toUpperCase()}`
+        : selected ? "✓ APPROVED" : stored.status === "applied" ? "○ EXCLUDED" : "○ NOT APPROVED";
+    console.log(box(lines, p, state).join("\n"));
+  }
+  if (stored.status === "approved") {
+    console.log(`\nNext: fullstackgtm apply --plan-id ${stored.plan.id} --provider <hubspot|salesforce>`);
+  }
+  console.log(`Details: fullstackgtm plans show ${stored.plan.id} --verbose`);
+}
+
+function printApplyCards(run: PatchPlanRun, plan: PatchPlan, approvedOperationIds: string[], planIdStored: boolean) {
+  const p = paint(colorEnabled(process.stdout));
+  const approved = new Set(approvedOperationIds);
+  const operations = new Map(plan.operations.map((operation) => [operation.id, operation]));
+  const counts = { applied: 0, skipped: 0, failed: 0, conflict: 0 };
+  for (const result of run.results) counts[result.status] += 1;
+  const elapsed = Math.max(0, Date.parse(run.finishedAt) - Date.parse(run.startedAt));
+  const summary = [
+    `Status    ${run.status.toUpperCase()}`,
+    `Provider  ${run.provider}`,
+    `Outcome   ${counts.applied} applied · ${run.results.length - approved.size} excluded · ${counts.failed + counts.conflict} failed/conflicted`,
+    `Duration  ${formatDuration(elapsed)}`,
+    ...(planIdStored ? ["Receipt   recorded locally; hosted reconciliation requested"] : []),
+  ];
+  console.log(box(summary, p, "Apply result").join("\n"));
+  console.log("\nOperations");
+  let index = 0;
+  for (const result of run.results) {
+    const operation = operations.get(result.operationId);
+    if (!operation) continue;
+    const selected = approved.has(result.operationId);
+    const headline = recordHeadline(operation);
+    const state = !selected ? "○ EXCLUDED" : result.status === "applied" ? "✓ APPLIED" : `! ${result.status.toUpperCase()}`;
+    const lines = [
+      headline.title,
+      ...(headline.subtitle || headline.company ? [[headline.subtitle, headline.company].filter(Boolean).join(" · ")] : []),
+      `Operation  ${result.operationId}`,
+      ...(result.detail ? [truncateToWidth(`Result     ${result.detail}`, 100)] : []),
+    ];
+    if (index++ > 0) console.log("");
+    console.log(box(lines, p, state).join("\n"));
+  }
+  if (planIdStored) console.log(`\nInspect: fullstackgtm plans show ${run.planId}`);
+  console.log("Details: rerun with --verbose; machine output: --json");
+}
+
 function tryLoadAcquireConfig(args: string[]): EnrichConfig | undefined {
   try {
     const path = resolve(process.cwd(), option(args, "--config") ?? ENRICH_CONFIG_FILE_NAME);
@@ -361,8 +470,10 @@ export async function apply(args: string[]) {
 
   if (args.includes("--json")) {
     console.log(JSON.stringify(run, null, 2));
-  } else {
+  } else if (args.includes("--verbose")) {
     console.log(formatPatchPlanRun(run));
+  } else {
+    printApplyCards(run, plan, approvedOperationIds, Boolean(planId && store));
   }
   if (run.status === "failed") process.exitCode = 1;
 }
@@ -484,14 +595,23 @@ export async function plansCommand(args: string[]) {
     }
     const p = paint(colorEnabled(process.stdout));
     if (p.enabled) {
-      // Interactive terminals get an aligned table with status color-banding;
-      // the plain per-line format below is unchanged for pipes.
+      const statusCounts = new Map<string, number>();
+      for (const stored of plans) statusCounts.set(stored.status, (statusCounts.get(stored.status) ?? 0) + 1);
+      const awaiting = plans.filter((stored) => stored.status === "needs_approval").length;
+      const approved = plans.filter((stored) => stored.status === "approved").length;
+      console.log(box([
+        `${plans.length} plan${plans.length === 1 ? "" : "s"} · ${awaiting} awaiting approval · ${approved} ready to apply`,
+        [...statusCounts.entries()].map(([name, count]) => `${name.replaceAll("_", " ")}: ${count}`).join("  ·  "),
+      ], p, "Change queue").join("\n"));
+      console.log("");
+      // Interactive terminals get an aligned decision table; the plain
+      // per-line format below remains stable for pipes and scripts.
       const rows = plans.map((stored) => [
-        stored.plan.id,
         stored.status,
-        `${stored.approvedOperationIds.length} approved`,
+        stored.plan.title,
+        `${stored.approvedOperationIds.length}/${stored.plan.operations.length} selected`,
         `${stored.runs.length} run${stored.runs.length === 1 ? "" : "s"}`,
-        stored.plan.summary,
+        stored.plan.id,
       ]);
       // Long summaries would wrap and break the table's alignment. The summary
       // is the LAST column: cap it to what's left of the terminal width after
@@ -499,19 +619,26 @@ export async function plansCommand(args: string[]) {
       // terminals still show something useful).
       const columns = process.stdout.columns ?? 80;
       const fixedWidth =
-        [0, 1, 2, 3].reduce(
+        [0, 2, 3, 4].reduce(
           (sum, index) => sum + Math.max(...rows.map((row) => row[index].length)),
           0,
         ) + 2 * 4;
-      const summaryWidth = Math.max(24, columns - fixedWidth);
-      for (const row of rows) row[4] = truncateToWidth(row[4], summaryWidth);
+      const titleWidth = Math.max(24, columns - fixedWidth);
+      for (const row of rows) row[1] = truncateToWidth(row[1], titleWidth);
       const statusPainter = (cell: string) => {
         const painted = planStatusWord(cell.trimEnd(), p);
         return painted + cell.slice(cell.trimEnd().length);
       };
-      for (const line of table(rows, [null, statusPainter, p.dim, p.dim, null])) {
+      for (const line of table(rows, [statusPainter, null, p.dim, p.dim, p.dim])) {
         console.log(line);
       }
+      const next = plans.find((stored) => stored.status === "approved") ?? plans.find((stored) => stored.status === "needs_approval");
+      if (next) {
+        const command = next.status === "approved"
+          ? `fullstackgtm apply --plan-id ${next.plan.id} --provider <name>`
+          : `fullstackgtm plans show ${next.plan.id}`;
+        console.log(`\nNext: ${command}`);
+      }
       return;
     }
     for (const stored of plans) {
@@ -538,22 +665,21 @@ export async function plansCommand(args: string[]) {
       console.log(JSON.stringify(stored, null, 2));
       return;
     }
-    const showPaint = paint(colorEnabled(process.stdout));
-    console.log(`Status: ${planStatusWord(stored.status, showPaint)}`);
-    console.log(`Approved operations: ${stored.approvedOperationIds.join(", ") || "none"}`);
-    console.log(`Runs: ${stored.runs.length}`);
     const mirror = await uploadHostedPatchPlan(stored);
-    if (mirror.status === "saved") console.log(`Hosted review: ${mirror.state.url}`);
-    else if (mirror.status === "unavailable" || mirror.status === "conflict") console.log(`Hosted review: sync pending (${mirror.reason})`);
-    if (stored.applyAttempts?.length) {
+    printPlanCards(stored, mirror.status === "saved" ? mirror.state.url : undefined);
+    if (mirror.status === "unavailable" || mirror.status === "conflict") console.log(`Hosted sync pending: ${mirror.reason}`);
+    if (rest.includes("--verbose") && stored.applyAttempts?.length) {
       console.log("Apply attempts:");
       for (const attempt of stored.applyAttempts) {
         console.log(`  ${attempt.id}  ${attempt.status}  ${attempt.provider} via ${attempt.source}  ${attempt.claimedAt}`);
         if (attempt.note) console.log(`    ${attempt.note}`);
       }
     }
-    console.log("");
-    console.log(stylizePlanMarkdown(patchPlanToMarkdown(stored.plan), showPaint));
+    if (rest.includes("--verbose")) {
+      const showPaint = paint(colorEnabled(process.stdout));
+      console.log("\nFull plan document\n");
+      console.log(stylizePlanMarkdown(patchPlanToMarkdown(stored.plan), showPaint));
+    }
     return;
   }
 
@@ -654,16 +780,35 @@ export async function plansCommand(args: string[]) {
   if (subcommand === "sync") {
     const plans = await store.list();
     let updated = 0;
+    let completed = 0;
     const warnings: string[] = [];
-    for (const stored of plans) {
-      const result = await reconcileHostedPatchPlan(store, stored);
-      if (result.status === "updated") updated += 1;
-      else if (result.status === "conflict" || result.status === "unavailable") warnings.push(`${stored.plan.id}: ${result.reason}`);
-      if (stored.status === "applied") {
-        const hostedClaimId = [...(stored.applyAttempts ?? [])].reverse().find((attempt) => attempt.hostedClaimId)?.hostedClaimId;
-        const pushed = await reportHostedPlanLifecycle(stored, { claimId: hostedClaimId });
-        if (pushed.status === "conflict" || pushed.status === "unavailable") warnings.push(`${stored.plan.id} receipt: ${pushed.reason}`);
+    const status = createStatusLine();
+    status.set(`Synchronizing plan replicas 0/${plans.length}`);
+    // A workspace can accumulate hundreds of local plans. Reconcile with a
+    // small worker pool so one network round-trip per plan does not turn into
+    // a minutes-long silent serial wait, without stampeding the hosted API.
+    let next = 0;
+    const worker = async () => {
+      while (next < plans.length) {
+        const stored = plans[next++];
+        const result = await reconcileHostedPatchPlan(store, stored);
+        if (result.status === "updated") updated += 1;
+        else if (result.status === "conflict" || result.status === "unavailable") warnings.push(`${stored.plan.id}: ${result.reason}`);
+        // Historical local-only plans have no remote row to receive a receipt.
+        // `backfill runs` is the explicit import path for that old history.
+        if (stored.status === "applied" && result.status !== "missing" && (stored.applyAttempts?.length ?? 0) > 0) {
+          const hostedClaimId = [...(stored.applyAttempts ?? [])].reverse().find((attempt) => attempt.hostedClaimId)?.hostedClaimId;
+          const pushed = await reportHostedPlanLifecycle(stored, { claimId: hostedClaimId });
+          if (pushed.status === "conflict" || pushed.status === "unavailable") warnings.push(`${stored.plan.id} receipt: ${pushed.reason}`);
+        }
+        completed += 1;
+        status.set(`Synchronizing plan replicas ${completed}/${plans.length}`);
       }
+    };
+    try {
+      await Promise.all(Array.from({ length: Math.min(6, plans.length) }, () => worker()));
+    } finally {
+      status.done();
     }
     console.log(`Plan replicas synchronized: ${updated} updated, ${plans.length - updated} unchanged.`);
     for (const warning of warnings) console.error(`  ${warning}`);

package/src/cli/schedule.ts

@@ -9,6 +9,7 @@ import { computeMissedFirings, createFileScheduleRunStore, createFileScheduleSto
 import { runCli } from "../cli.ts";
 import { isOptionValue, numericOption, option } from "./shared.ts";
 import { unknownSubcommandError } from "./suggest.ts";
+import { colorEnabled, paint, table } from "./ui.ts";
 
 
 /**
@@ -120,12 +121,19 @@ trigger: manual. status shows next firing and surfaces missed firings
       console.log('No schedules. Add one with `fullstackgtm schedule add "<command>" --cron "<expr>"`.');
       return;
     }
-    for (const entry of withNext) {
-      console.log(
-        `${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron.padEnd(14)} next ${entry.nextFiring ?? "—"}  ${entry.label}: ${entry.argv.join(" ")}`,
-      );
-    }
-    console.log("\nEntries are declarative — `schedule install` materializes enabled ones into the crontab.");
+    const p = paint(colorEnabled(process.stdout));
+    const verbose = rest.includes("--verbose");
+    const rows = [
+      ["STATE", "SCHEDULE", "NEXT", ...(verbose ? ["CRON", "COMMAND"] : [])],
+      ...withNext.map((entry) => [
+        entry.enabled ? "on" : "off",
+        `${entry.label} · ${entry.id}`,
+        entry.nextFiring ?? "—",
+        ...(verbose ? [entry.cron, entry.argv.join(" ")] : []),
+      ]),
+    ];
+    console.log(table(rows, [p.dim, null, null]).join("\n"));
+    console.log("\nDeclarative only · run `fullstackgtm schedule install` after changes.");
     return;
   }
 
@@ -272,21 +280,19 @@ trigger: manual. status shows next firing and surfaces missed firings
       const last = entry.lastRun as { firedAt: string; trigger: string; exitCode: number; noopReason?: string; artifacts: { planIds: string[]; runLabels: string[] } } | null;
       const streak = entry.streak as { outcome: string; length: number } | null;
       const missed = entry.missedFirings as string[];
-      console.log(`${entry.id}  ${entry.enabled ? "on " : "off"}  ${entry.cron}  ${entry.label}: ${(entry.argv as string[]).join(" ")}`);
-      console.log(`  next: ${entry.nextFiring ?? "— (disabled)"}`);
+      const verbose = rest.includes("--verbose");
+      const outcome = !last ? "never run" : last.exitCode === 0 ? (last.noopReason ? `no-op · ${last.noopReason}` : "healthy") : `failed · exit ${last.exitCode}`;
+      console.log(`${entry.enabled ? "●" : "○"} ${entry.label} · ${outcome}`);
+      console.log(`  ${entry.id} · next ${entry.nextFiring ?? "— (disabled)"}`);
+      if (verbose) console.log(`  ${(entry.argv as string[]).join(" ")} · cron ${entry.cron}`);
       if (last) {
         const artifacts = [
           ...last.artifacts.planIds.map((planId) => `plan ${planId}`),
           ...last.artifacts.runLabels.map((runLabel) => `run ${runLabel}`),
         ];
-        console.log(
-          `  last: ${last.firedAt} (${last.trigger}) exit ${last.exitCode}` +
-            (last.noopReason ? ` — no-op: ${last.noopReason}` : "") +
-            (artifacts.length ? ` — ${artifacts.join(", ")}` : ""),
-        );
-        console.log(`  streak: ${streak!.length} ${streak!.outcome}(s)`);
+        console.log(`  last ${last.firedAt} · ${last.trigger} · ${streak!.length} ${streak!.outcome}${streak!.length === 1 ? "" : "s"}${artifacts.length ? ` · ${artifacts.join(", ")}` : ""}`);
       } else {
-        console.log("  last: never fired");
+        console.log("  last never fired");
       }
       if (missed.length > 0) {
         console.log(

package/src/cli/signals.ts

@@ -27,6 +27,21 @@ function resolveSignalsConfig(args: string[]): SignalsConfig {
 /** A watchlist entry: an account domain plus optional per-source board tokens. */
 type WatchlistAccount = { domain: string; boards?: Partial<Record<AtsBoardSource, string>> };
 
+function concise(value: string, max = 72): string {
+  const oneLine = value.replace(/\s+/g, " ").trim();
+  return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}
+
+function renderSignals(signals: Signal[]): string {
+  if (signals.length === 0) return "No signals matched.";
+  const lines = [`Fresh signals (${signals.length})`, ""];
+  for (const signal of signals) {
+    lines.push(`${signal.weight.toFixed(2).padStart(5)}  ${signal.accountDomain}  · ${signal.bucket}`);
+    lines.push(`       ${concise(signal.trigger)}`);
+  }
+  return lines.join("\n");
+}
+
 /**
  * Resolve the watchlist of accounts to scan. Sources, in precedence order:
  *  - a --watchlist file (JSON array of {domain, boards?} or bare domain strings),
@@ -228,7 +243,7 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
     const ranked = [...fresh].sort((a, b) => b.weight - a.weight || a.accountDomain.localeCompare(b.accountDomain));
 
     // Ranked fresh signals to stdout; guidance to stderr.
-    console.log(JSON.stringify(ranked, null, 2));
+    console.log(rest.includes("--json") || rest.includes("--verbose") ? JSON.stringify(ranked, null, 2) : renderSignals(ranked));
     console.error(
       `Fetched ${fetched} candidate signal(s); ${fresh.length} fresh, ${deduped.length} deduped ` +
         `(window ${config.dedupWindowDays}d). NO plan emitted — signals are read-only re: CRM.`,
@@ -275,7 +290,7 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
       return true;
     });
     const ranked = filtered.sort((a, b) => b.weight - a.weight || a.accountDomain.localeCompare(b.accountDomain));
-    console.log(JSON.stringify(ranked, null, 2));
+    console.log(rest.includes("--json") || rest.includes("--verbose") ? JSON.stringify(ranked, null, 2) : renderSignals(ranked));
     console.error(`${ranked.length} signal(s)${unjudgedOnly ? " (unjudged)" : ""}.`);
     return;
   }
@@ -305,7 +320,11 @@ from the credential ladder, never argv; --connector-opt carries non-secret knobs
     const outcomes = await store.listOutcomes();
     const signalsById = new Map((await store.allSignals()).map((s) => [s.id, s]));
     const weights = computeWeights(config, outcomes, signalsById);
-    console.log(JSON.stringify(weights, null, 2));
+    if (rest.includes("--json") || rest.includes("--verbose")) {
+      console.log(JSON.stringify(weights, null, 2));
+    } else {
+      console.log(["Learned signal weights", "", ...SIGNAL_BUCKETS.map((bucket) => `${bucket.padEnd(10)} ${weights[bucket].toFixed(4)}`)].join("\n"));
+    }
     if (rest.includes("--explain")) {
       // Per-bucket config default vs learned + booked/total over credited signals.
       const booked = new Map<SignalBucket, number>();

package/src/cli/tam.ts

@@ -6,6 +6,7 @@ import { getCredential } from "../credentials.ts";
 import { appendCoverage, computeCoverage, coverageCountsFromSnapshot, classifyCoverage, coverageToText, deriveAcvFromClosedWon, deriveBuyersPerAccount, estimateTam, loadTamModel, projectEta, readCoverageTimeline, saveTamModel, tamReportToMarkdown, type AcvBasis, type TamCrossCheck } from "../tam.ts";
 import { probeExploriumBusinessCount } from "../connectors/prospectSources.ts";
 import { theirStackCountCompanies, theirStackPullCost, theirStackSearchCompanies } from "../connectors/theirstack.ts";
+import { clayApiKey } from "../connectors/clay.ts";
 import { icpToExploriumBusinessFilters, icpToTheirStackFilters } from "../icp.ts";
 import { scheduleCommand } from "./schedule.ts";
 import { loadIcp, numericOption, option, readSnapshot, saveRequested } from "./shared.ts";
@@ -14,7 +15,8 @@ import { unknownSubcommandError } from "./suggest.ts";
 
 /** Best-effort enrich-config load for apply-time acquire-budget enforcement. */
 /** Provider API key: env override first, then the credential store (`login`). */
-export function providerKey(provider: "explorium" | "pipe0" | "heyreach" | "theirstack"): string {
+export function providerKey(provider: "explorium" | "pipe0" | "clay" | "heyreach" | "theirstack"): string {
+  if (provider === "clay") return clayApiKey();
   const envName =
     provider === "explorium"
       ? "EXPLORIUM_API_KEY"
@@ -44,7 +46,7 @@ export async function tamCommand(args: string[]) {
   fullstackgtm tam accounts [--name <n>] [--icp <path>] --source theirstack [--max <n>] [--dry-run | --confirm] [--max-credits <n>] [--usd-per-credit <r>] [--out <file.csv> | --json]
   fullstackgtm tam status   [--name <n>] <source options> [--save] [--json]
   fullstackgtm tam report   [--name <n>] [--out <path>]
-  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|linkedin] [--provider hubspot|salesforce] [--label <l>]
+  fullstackgtm tam populate [--name <n>] --cron "<expr>" [--source pipe0|explorium|clay|linkedin] [--provider hubspot|salesforce] [--label <l>]
 
 Estimate the reachable market FROM your ICP: a real account count × a confirmed
 ANNUAL ACV (--acv <annual-usd>, or --acv-from-crm --deal-period monthly|quarterly|
@@ -275,8 +277,15 @@ RevOps universe, with real names. --source explorium is a firmographic count onl
     if (out) {
       writeFileSync(resolve(process.cwd(), out), md);
       console.log(`Wrote ${out}.`);
-    } else {
+    } else if (rest.includes("--verbose")) {
       console.log(md);
+    } else if (timeline.length > 0) {
+      console.log(coverageToText(model, timeline.at(-1)!, eta));
+      console.log("\nUse --verbose for assumptions, cross-checks, and the full coverage history.");
+    } else {
+      console.log(`TAM "${model.name}" · ${model.universe.accounts.toLocaleString()} accounts · ${model.universe.contacts.toLocaleString()} buyers · $${Math.round(model.tamUsd).toLocaleString()}`);
+      console.log(`ICP ${model.icpName} · ${model.acv.basis}-basis ACV $${Math.round(model.acv.valueUsd).toLocaleString()} (${model.acv.source})`);
+      console.log("No coverage readings yet. Run `fullstackgtm tam status --save` to establish one; use --verbose for the full assumptions report.");
     }
     return;
   }

package/src/cli/ui.ts

@@ -324,8 +324,12 @@ export function createChecklist(
       const label = entry.state === "pending" ? p.dim(item.label.padEnd(labelWidth)) : item.label.padEnd(labelWidth);
       return `  ${glyph} ${label}${note}`;
     });
-    const up = painted > 0 ? `\u001b[${painted}A` : "";
-    stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}\n`);
+    // Keep the cursor on the board's last row while it is live. A trailing
+    // newline on every repaint can scroll the old top row into permanent
+    // history when the board sits at the bottom of the terminal, producing
+    // apparent duplicate/errored frames in terminal captures.
+    const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+    stream.write(`${up}${lines.map((line) => `\u001b[2K${line}`).join("\n")}`);
     painted = lines.length;
   };
 
@@ -353,14 +357,19 @@ export function createChecklist(
       timer = null;
       if (options.persist) {
         // The caller's final state update already painted the completed board.
-        // Freeze that frame in scrollback; repainting here can leave both the
-        // last live frame and the final frame visible in some terminals.
+        // Advance exactly once so subsequent output begins below it.
+        if (painted > 0) stream.write("\n");
         painted = 0;
         return;
       }
       if (painted > 0) {
-        // Erase the board: cursor up over every painted line, clear each.
-        stream.write(`\u001b[${painted}A${"\u001b[2K\n".repeat(painted)}\u001b[${painted}A`);
+        // Erase in place without linefeeds, which could themselves scroll.
+        const up = painted > 1 ? `\u001b[${painted - 1}A` : "";
+        const clear = Array.from({ length: painted }, (_, index) =>
+          `\u001b[2K${index < painted - 1 ? "\u001b[1B" : ""}`,
+        ).join("");
+        const restore = painted > 1 ? `\u001b[${painted - 1}A` : "";
+        stream.write(`${up}${clear}${restore}`);
         painted = 0;
       }
     },

package/src/connectors/clay.ts

@@ -0,0 +1,155 @@
+import { getCredential } from "../credentials.ts";
+import { ProviderHttpError } from "../providerError.ts";
+import type { Prospect } from "./prospectSources.ts";
+
+export const CLAY_PUBLIC_API_BASE = "https://api.clay.com/public/v0";
+
+export type ClayKeyValidation = {
+  ok: boolean;
+  detail: string;
+  workspaceId?: string;
+};
+
+export type ClaySearchSourceType = "people" | "companies";
+
+export type ClayPeopleSearchPage = {
+  prospects: Prospect[];
+  hasMore: boolean;
+};
+
+function clayHeaders(apiKey: string): Record<string, string> {
+  return { "clay-api-key": apiKey, Accept: "application/json", "Content-Type": "application/json" };
+}
+
+/** Create a forward-only Clay search iterator. This call does not fetch a page. */
+export async function createClaySearch(opts: {
+  apiKey: string;
+  sourceType: ClaySearchSourceType;
+  filters: Record<string, unknown>;
+  fetchImpl?: typeof fetch;
+  apiBaseUrl?: string;
+}): Promise<string> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+  const response = await fetchImpl(`${base}/search/filters-mode`, {
+    method: "POST",
+    headers: clayHeaders(opts.apiKey),
+    body: JSON.stringify({ source_type: opts.sourceType, filters: opts.filters }),
+  });
+  if (!response.ok) throw new ProviderHttpError("Clay", "create search", response.status);
+  const body = await response.json() as { search_id?: unknown; searchId?: unknown };
+  const searchId = body.search_id ?? body.searchId;
+  if (typeof searchId !== "string" || !searchId) throw new Error("Clay create search returned no search_id.");
+  return searchId;
+}
+
+/** Consume the next people page from a Clay search iterator. */
+export async function runClayPeopleSearchPage(opts: {
+  apiKey: string;
+  searchId: string;
+  limit?: number;
+  fetchImpl?: typeof fetch;
+  apiBaseUrl?: string;
+}): Promise<ClayPeopleSearchPage> {
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const base = (opts.apiBaseUrl ?? CLAY_PUBLIC_API_BASE).replace(/\/$/, "");
+  const limit = Math.max(1, Math.min(opts.limit ?? 25, 100));
+  const response = await fetchImpl(`${base}/search/filters-mode/${encodeURIComponent(opts.searchId)}/run`, {
+    method: "POST",
+    headers: clayHeaders(opts.apiKey),
+    body: JSON.stringify({ limit }),
+  });
+  if (!response.ok) throw new ProviderHttpError("Clay", "run people search", response.status);
+  const body = await response.json() as { data?: unknown; has_more?: unknown; hasMore?: unknown };
+  if (!Array.isArray(body.data)) throw new Error("Clay people search returned an invalid data array.");
+  const hasMore = body.has_more ?? body.hasMore;
+  if (typeof hasMore !== "boolean") throw new Error("Clay people search returned no has_more flag.");
+  return { prospects: body.data.map(normalizeClayPerson), hasMore };
+}
+
+export function normalizeClayPerson(value: unknown): Prospect {
+  const row = value && typeof value === "object" ? value as Record<string, unknown> : {};
+  const location = row.structured_location && typeof row.structured_location === "object"
+    ? row.structured_location as Record<string, unknown>
+    : {};
+  const fullName = stringValue(row.name);
+  return {
+    firstName: stringValue(row.first_name),
+    lastName: stringValue(row.last_name),
+    fullName,
+    jobTitle: stringValue(row.latest_experience_title),
+    companyName: stringValue(row.latest_experience_company),
+    companyDomain: bareDomain(stringValue(row.domain)),
+    linkedin: normalizeLinkedin(stringValue(row.url)),
+    headline: undefined,
+    sourceId: normalizeLinkedin(stringValue(row.url)) ?? fullName,
+    location: {
+      city: stringValue(location.city),
+      state: stringValue(location.state),
+      region: stringValue(location.region),
+      country: stringValue(location.country),
+      countryCode: stringValue(location.country_iso),
+    },
+  };
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function bareDomain(value: string | undefined): string | undefined {
+  return value?.replace(/^https?:\/\//i, "").replace(/^www\./i, "").replace(/\/.*$/, "").toLowerCase() || undefined;
+}
+
+function normalizeLinkedin(value: string | undefined): string | undefined {
+  if (!value) return undefined;
+  const normalized = value.startsWith("http") ? value : `https://${value.replace(/^\/+/, "")}`;
+  return normalized.replace(/\/$/, "");
+}
+
+/** Validate a Clay Public API key without creating a search or spending enrichment credits. */
+export async function validateClayApiKey(
+  apiKey: string,
+  fetchImpl: typeof fetch = fetch,
+  apiBaseUrl = CLAY_PUBLIC_API_BASE,
+): Promise<ClayKeyValidation> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${apiBaseUrl.replace(/\/$/, "")}/me`, {
+      headers: { "clay-api-key": apiKey, Accept: "application/json" },
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    return { ok: false, detail: `Cannot reach the Clay Public API: ${detail}` };
+  }
+  if (!response.ok) return { ok: false, detail: `Clay rejected the key: HTTP ${response.status}` };
+  let body: unknown;
+  try {
+    body = await response.json();
+  } catch {
+    return { ok: false, detail: "Clay accepted the request but returned an invalid JSON response." };
+  }
+  const record = body && typeof body === "object" ? body as Record<string, unknown> : {};
+  const workspace = record.workspace && typeof record.workspace === "object"
+    ? record.workspace as Record<string, unknown>
+    : undefined;
+  const rawWorkspaceId = record.workspace_id ?? record.workspaceId ?? workspace?.id;
+  const workspaceId = typeof rawWorkspaceId === "string" || typeof rawWorkspaceId === "number"
+    ? String(rawWorkspaceId)
+    : undefined;
+  return {
+    ok: true,
+    detail: workspaceId ? `Key accepted by Clay workspace ${workspaceId}.` : "Key accepted by the Clay Public API.",
+    workspaceId,
+  };
+}
+
+/** Resolve Clay credentials using the standard env -> profile-scoped store ladder. */
+export function clayApiKey(env: Record<string, string | undefined> = process.env): string {
+  const key = env.CLAY_API_KEY ?? getCredential("clay")?.accessToken;
+  if (key) return key;
+  throw new Error(
+    'No Clay credentials. Run `clay api-keys create --name "fullstackgtm"`, then pipe the key to ' +
+      '`fullstackgtm login clay`, or set CLAY_API_KEY.',
+  );
+}