@oxygen-agent/cli 1.936.1 → 1.948.1

package/dist/index.js

@@ -200,8 +200,13 @@ function buildFindBody(capability, options) {
     }
     if (options.mode)
         body.mode = options.mode;
-    const maxCredits = readPositiveNumber(options.maxCredits);
-    if (maxCredits)
+    // Company only: 0 is a real ceiling meaning "run only the zero-credit lanes".
+    // The person capabilities are paid on every lane, so 0 stays a usage error
+    // there. `!== undefined` because 0 is falsy and would otherwise be dropped.
+    const maxCredits = capability === "company"
+        ? readCreditCeilingOrZero(options.maxCredits)
+        : readPositiveNumber(options.maxCredits);
+    if (maxCredits !== undefined)
         body.max_credits = maxCredits;
     // Phone-only opt-in; the route ignores it for other capabilities.
     if (options.verify)
@@ -443,6 +448,33 @@ function emitCliFailure(command, error) {
     writeMaxCreditsHint(error);
     process.exitCode = error instanceof OxygenError ? exitCodeForOxygenError(error) : 1;
 }
+// A post's engagers list is the one payload in this tree that is routinely
+// thousands of lines long, and the field that decides whether you may act on it
+// — `truncated` — is one boolean inside it. Printed raw, a partial audience
+// looks exactly like a whole one until you scroll past every person in it. So
+// lead with the receipt on stderr (the same stdout/stderr split the dry-run and
+// credits notices use, leaving stdout a clean envelope) and say plainly what to
+// do about a short read. `--json` callers are untouched: they read the fields.
+function writeEngagersReceipt(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return;
+    const record = data;
+    const pages = isRecord(record.pages_read) ? record.pages_read : {};
+    const line = (text) => process.stderr.write(`${text}\n`);
+    line(`Post ${String(record.post ?? "?")}`);
+    line(`  ${String(record.total_engagers ?? 0)} engagers`
+        + ` (${String(record.reactors_count ?? 0)} reactions, ${String(record.commenters_count ?? 0)} comments)`
+        + ` from ${String(pages.reactions ?? 0)}+${String(pages.comments ?? 0)} pages`);
+    if (record.truncated === true) {
+        const reason = typeof record.partial_reason === "string" ? record.partial_reason : "unknown";
+        line(`  PARTIAL (${reason}) — this post has more engagers than were read.`);
+        line(reason === "max_pages"
+            ? "  Raise --max-pages (max 20), or run `oxygen engagement harvest` to walk the whole post into a table."
+            : "  Retry, or run `oxygen engagement harvest` to walk the whole post into a table.");
+    }
+    if (typeof record.web_url === "string")
+        line(`  ${record.web_url}`);
+}
 // A dry run's stdout envelope looks like a successful result — same shape, same
 // `ok: true` — so in a terminal the only tell that nothing was fetched was
 // `meta.mode` buried inside the payload. That is how a working provider key gets
@@ -5013,7 +5045,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Source EXTERNAL market signals into a table: hiring, technology adoption, funding, acquisitions, and news. This is the sourcing half of Signals — `signals list` reads the events already captured for your workspace.")
         .addCommand(new Command("plan")
         .description("Compile a signal-sourcing request into ordered provider routes without provider calls: the chain, per-route applied/dropped filters, credit estimate, table blueprint, and whether the route can be kept LIVE on a cadence. Free.")
-        .requiredOption("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file.")
         .requiredOption("--family <family>", "Signal family: hiring, tech, funding, acquisition, news, or job_change.")
         .option("--scope <scope>", "market (discover new companies) or watch_list (track companies you name via --domains). Defaults per family.")
         .option("--target-count <n>", "Desired row count for routing and estimates.")
@@ -5027,14 +5060,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--filters-json <json-or-file>", "Filters JSON inline or a path to a JSON file; wins over individual flags per top-level filter path.")
         .option("--estimate", "Run the free server-side preflight pass: resolves provider enum values and, where a provider publishes one, a free match count (zero credits).")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("signals search plan", options, () => requestOxygen("/api/cli/signals/search/plan", {
             method: "POST",
-            body: readSignalsSearchPlanBody(options),
+            body: readSignalsSearchPlanBody(options, promptArg),
         }));
     }))
         .addCommand(new Command("run")
         .description("Return a dry-run request or queue a live signal-search ingestion run. Live requires --approved and --max-credits. Add --bind-feed --every to also bind a pull feed to the same table in the same call, so the table keeps refilling on a cadence.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt); requires --family. The --prompt flag wins if both are given.")
         .option("--prompt <text-or-file>", "Signal-sourcing prompt, or a path to a prompt file. Requires --family.")
         .option("--plan-json <json-or-file>", "Plan JSON returned by signals search plan, or a path to a JSON file.")
         .option("--family <family>", "Signal family when planning from --prompt: hiring, tech, funding, acquisition, news, or job_change.")
@@ -5062,10 +5096,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--max-credits-per-cycle <n>", "Credit ceiling PER sync cycle for the bound feed.")
         .option("--max-rows-per-cycle <n>", "Advisory row ceiling per sync cycle for the bound feed.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("signals search run", options, () => requestOxygen("/api/cli/signals/search/run", {
             method: "POST",
-            body: readSignalsSearchRunBody(options),
+            body: readSignalsSearchRunBody(options, promptArg),
         }));
     })));
     const tablesCommand = program
@@ -5478,6 +5512,63 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             });
         });
     }));
+    const watcherCommand = tablesCommand.command("watcher")
+        .description("LinkedIn Profile Watcher: one editable table of daily engagers, source attribution, and current employers from posts in the past 7 days. Start with preview (free); create/resume activate paid daily monitoring after exact approval.");
+    watcherCommand.command("get")
+        .description("Read a table's LinkedIn Profile Watcher configuration and status. Free.")
+        .argument("<table>", "Watcher table id or slug.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (table, options) => {
+        await handleAsyncAction("tables watcher get", options, () => requestOxygen(`/api/cli/tables/linkedin-profile-watcher?table=${encodeURIComponent(table)}`, { method: "GET" }));
+    });
+    for (const action of ["preview", "create", "update", "pause", "resume"]) {
+        const command = watcherCommand.command(action)
+            .description({
+            preview: "Free configuration and credit preview: no provider calls, writes, or scheduling. Omit --max-credits for a recommendation and preview hash. Ask for real profile URLs; never invent them.",
+            create: "Create and activate a LinkedIn Profile Watcher after approval of its exact preview. Starts collection now and daily at 07:00 UTC under the approved per-cycle cap.",
+            update: "Edit watched profiles or the per-cycle cap from the table. Preview the changes first; approval binds the exact new configuration.",
+            pause: "Pause daily monitoring while retaining the table and collected rows.",
+            resume: "Resume paid daily monitoring after reviewing a fresh preview and approving its per-cycle credit cap.",
+        }[action])
+            .option("--table <table>", "Existing watcher table id or slug; required for get/update/pause/resume.")
+            .option("--json", "Print a JSON envelope.");
+        if (action !== "pause") {
+            command
+                .option("--name <name>", "Watcher table display name.")
+                .option("--project <project>", "Project id or slug; defaults to General.")
+                .option("--profiles-json <json>", "JSON array of 1–10 real public LinkedIn profile URLs; replaces the watched list.")
+                .option("--max-credits <credits>", "Hard credit ceiling for each daily cycle; never a monthly ceiling.");
+            if (action !== "preview")
+                command
+                    .option("--preview-hash <hash>", "Exact configuration hash returned by preview; re-preview after any change.")
+                    .option("--approved", "Approve this exact configuration and recurring per-cycle spending.");
+        }
+        if (action === "create") {
+            command.requiredOption("--request-id <uuid>", "One stable UUID for this new watcher. Reuse it and the identical configuration after a timeout; never generate a new retry key.");
+        }
+        command.action(async (options) => {
+            await handleAsyncAction(`tables watcher ${action}`, options, () => {
+                const profiles = options.profilesJson === undefined ? undefined : parseJsonArray(options.profilesJson);
+                if (profiles !== undefined && profiles.some((profile) => typeof profile !== "string")) {
+                    throw new OxygenError("invalid_input", "--profiles-json must be an array of LinkedIn profile URL strings.");
+                }
+                return requestOxygen("/api/cli/tables/linkedin-profile-watcher", {
+                    method: "POST",
+                    body: {
+                        action,
+                        ...(readOption(options.table) ? { table: readOption(options.table) } : {}),
+                        ...(readOption(options.name) ? { name: readOption(options.name) } : {}),
+                        ...(readOption(options.project) ? { project: readOption(options.project) } : {}),
+                        ...(profiles !== undefined ? { profiles } : {}),
+                        ...(options.maxCredits !== undefined ? { max_credits_per_cycle: readPositiveNumber(options.maxCredits) } : {}),
+                        ...(readOption(options.requestId) ? { request_id: readOption(options.requestId) } : {}),
+                        ...(readOption(options.previewHash) ? { preview_hash: readOption(options.previewHash) } : {}),
+                        ...(options.approved ? { approved: true } : {}),
+                    },
+                });
+            });
+        });
+    }
     tablesCommand.addCommand(new Command("relate")
         .description("Relate two tables: define empty Tables-owned relation columns on the source and target. Then use `oxygen tables link` to populate row-to-row edges. Works on any workspace table; plain tables stay plain and are never registered as CRM objects. Defaults to dry-run.")
         .argument("<table>", "Source table id or slug.")
@@ -7468,10 +7559,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .argument("<table>", "Table id or slug.")
         .option("--preset <preset>", "Add a pre-built enrichment bundle instead of one column: `person_enrich` (one LinkedIn profile lookup, then headline, bio, location and followers for free) or `company_enrich` (domain, LinkedIn page, headcount, industry and full profile, cascading across providers until one answers). Oxygen finds the identity column itself — override with --input. Creating the columns is free; run them afterwards, --dry-run first.")
         .option("--input <slot=column...>", "Bind a preset input to an exact column, e.g. --input url=linkedin_url, or --input company_name=account --input domain=website. Repeatable. Only needed when the automatic match is wrong or missing.", collectRepeatable, [])
-        .option("--label <label>", "Display label for the new column. Required unless --prompt-key supplies a default title.")
+        .option("--capability <capability>", "Seed a ready-to-run enrichment column WITHOUT running it (0 credits): verify_email grades the address a row already holds \u2014 MillionVerifier first, catch-all domains escalate to BounceBan; work_email, mobile_phone and linkedin_url find a value the row is missing through the managed waterfall. Sets kind=enrichment and jsonb; label and key default from the capability. Preview cost with `enrich-column preview --capability <same>` and run later with `enrich-column run --approved --max-credits <n>`.")
+        .option("--label <label>", "Display label for the new column. Required unless --prompt-key or --capability supplies a default title.")
         .option("--key <key>", "Optional stable column key. Defaults to a normalized label.")
         .option("--data-type <type>", "Column data type: text, numeric, boolean, jsonb, or timestamptz.")
-        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
+        .option("--kind <kind>", "Column kind: manual, research, ai, formula, enrichment, tool, bind, or lookup. Defaults to manual. Use research for anything you would look up on the web. Enrichment columns always hold a jsonb cell, and --data-type is set for you \u2014 use --capability to seed a ready-to-run one. `lookup` reads a value out of another table; to LINK two tables row-to-row use `oxygen tables relate` instead \u2014 relation columns are two-sided and cannot be added here.")
         .option("--semantic-type <type>", "Optional semantic type such as company_domain.")
         .option("--definition-json <json>", "Optional JSON object with column definition metadata.")
         .option("--prompt <text-or-file>", "AI or research column prompt, or a path to a prompt file — a value that resolves to a readable file is read as one, matching --prompt everywhere else in this CLI. On its own it sets kind=ai; pair it with --kind research to search the web per row instead. If the prompt names its output sections — a line reading 'Return the following sections:' followed by 'Score: ...', 'Reasoning: ...' — the column answers in exactly that shape and each section becomes a referenceable sub-column; otherwise it answers in plain text. Use --no-structured-output to keep it plain text either way. Reference other columns inline as {{column_key}} — no --input-mapping needed; unknown keys are rejected here instead of failing per row. Merges into --definition-json (the escape hatch for everything else); a `prompt` in both is an error.")
@@ -7505,6 +7597,36 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         // skipcq: JS-R1005 — intentional per-option branching to assemble the columns-add request body
         .action(async (table, options) => {
         await handleAsyncAction("columns add", options, async () => {
+            // --capability seeds a COMPLETE enrichment column server-side (kind,
+            // jsonb data type, intent, the default provider order, label and
+            // key), so any flag that authors a different column is a conflict,
+            // not a modifier. Caught here rather than server-side so the user
+            // never gets back a column they did not ask for.
+            const capability = readOption(options.capability);
+            if (capability) {
+                const conflicting = [
+                    readOption(options.preset) ? "--preset" : null,
+                    readOption(options.prompt) ? "--prompt" : null,
+                    readOption(options.promptKey) ? "--prompt-key" : null,
+                    readOption(options.bindObject) ? "--bind-object" : null,
+                    readOption(options.bindMap) ? "--bind-map" : null,
+                    options.bindCreate ? "--bind-create" : null,
+                    readOption(options.lookupTable) ? "--lookup-table" : null,
+                    readOption(options.lookupMatch) ? "--lookup-match" : null,
+                    readOption(options.lookupMode) ? "--lookup-mode" : null,
+                    readOption(options.lookupReturn) ? "--lookup-return" : null,
+                    readOption(options.lookupOrder) ? "--lookup-order" : null,
+                    readOption(options.lookupAggregate) ? "--lookup-aggregate" : null,
+                    readOption(options.lookupNormalize) ? "--lookup-normalize" : null,
+                ].filter((flag) => flag !== null);
+                if (conflicting.length > 0) {
+                    throw new OxygenError("invalid_request", `--capability ${capability} seeds a complete enrichment column, so it cannot be combined with ${conflicting.join(", ")}. Drop one of the two.`, { exitCode: 1 });
+                }
+                const capabilityKind = readOption(options.kind)?.toLowerCase() ?? null;
+                if (capabilityKind && capabilityKind !== "enrichment") {
+                    throw new OxygenError("invalid_request", `--capability authors an enrichment column, but --kind ${capabilityKind} was requested. Drop --kind, or drop --capability.`, { exitCode: 1 });
+                }
+            }
             // A preset names its own columns, so --label does not apply to it.
             const preset = readOption(options.preset);
             if (preset) {
@@ -7522,7 +7644,9 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                     body: presetBody,
                 });
             }
-            if (!options.promptKey && !options.label) {
+            // --capability supplies its own label ("Email Verification", ...)
+            // server-side, the same one the web picker writes.
+            if (!options.promptKey && !capability && !options.label) {
                 throw new OxygenError("invalid_request", "--label is required.", { exitCode: 1 });
             }
             if (options.promptKey && !options.inputMapping) {
@@ -7547,6 +7671,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 column.definition = parseJsonObject(options.definitionJson);
             const requestedKind = readOption(options.kind)?.toLowerCase() ?? null;
             const isResearch = requestedKind === "research";
+            if (capability)
+                column.capability = capability;
+            // An enrichment cell is always the provider envelope, so the server
+            // rejects any other data type ("Enrichment columns must use jsonb
+            // data type."). Default it, the way --bind-object already does,
+            // instead of making the caller bolt on --data-type jsonb.
+            if (requestedKind === "enrichment" && !options.dataType) {
+                column.data_type = "jsonb";
+            }
             if (prompt !== null) {
                 if (requestedKind && requestedKind !== "ai" && !isResearch) {
                     throw new OxygenError("invalid_request", `--prompt authors an AI or research column, but --kind ${requestedKind} was requested. Drop --kind, or drop --prompt.`, { exitCode: 1 });
@@ -7652,7 +7785,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .argument("<column>", "Column id or key.")
         .option("--row-id <row_id>", "Workspace row id to run. Get one from `oxygen tables query <table> --limit 1 --json` — the field is `_row_id`, not `id`.")
         .option("--limit <n>", "Run the next N rows whose target cell is still empty (--force runs the first N regardless). Repeat until rowCount is 0 to page through a table. Defaults to 10; inline deterministic runs have a hard cap of 25.")
-        .option("--all", "Run all rows. Requires --background.")
+        .option("--all", "Run all rows. Requires --background, except with --dry-run, which previews the background run without queueing it.")
         .option("--filter-json <json>", "Row selector filter object or array for background runs. Do not combine with --all, --limit, or --row-id.")
         .option("--formula-values <mode>", "With --filter-json on a formula column, first refresh that selector with `columns run <table> <column> --force` (0 credits), then pass 'materialized'. The run filters the stored snapshot and persists this freshness acknowledgement.")
         .option("--force", "Run even when the target cell already has a value.")
@@ -7685,18 +7818,27 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             Boolean(readOption(options.rowId)),
             Boolean(effectiveFilterSelection),
         ].filter(Boolean).length;
-        if (selectedModes > 1) {
-            throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
-                exitCode: 1,
-            });
-        }
-        if (options.all && !options.background) {
-            throw new OxygenError("invalid_column_run", "--all requires --background.", {
-                exitCode: 1,
-            });
-        }
         // skipcq: JS-R1005 — intentional branching for local/background/filter column-run modes
         await handleAsyncAction("columns run", options, async () => {
+            // Selection-shape errors are raised inside the action so --json
+            // callers get the failure envelope, not a bare stack trace.
+            if (selectedModes > 1) {
+                throw new OxygenError("invalid_selection", "Pass only one of --all, --limit, --row-id, or --filter-json.", {
+                    exitCode: 1,
+                });
+            }
+            // A dry run of an all-rows run previews the background run the live
+            // command would create and queues nothing, so demanding --background
+            // for it only teaches a flag with no behavioural basis (blind eval
+            // 2026-09-10: the agent tripped the error, then re-ran with the flag).
+            if (options.all && options.dryRun && !options.background && !options.local) {
+                options.background = true;
+            }
+            if (options.all && !options.background) {
+                throw new OxygenError("invalid_column_run", "--all requires --background.", {
+                    exitCode: 1,
+                });
+            }
             if (options.local) {
                 if (options.background) {
                     throw new OxygenError("invalid_column_run", "Pass either --local or --background, not both.", {
@@ -8539,7 +8681,8 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Plan, dry-run, or queue provider-backed company search.")
         .addCommand(new Command("plan")
         .description("Compile a company-search prompt into ordered provider routes without provider calls.")
-        .requiredOption("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
+        .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
         .option("--target-count <n>", "Desired company count. Single-plan ceiling 50,000; larger requests return an explicit clamp warning and segmentation guidance.")
         .option("--source-intent <intent>", "Override detected intent: sizing, structured, lookalike, technology, hiring, local, known_source, concept, web, url, or fallback.")
         .option("--filters-json <json-or-file>", "CompanySearchFilters JSON inline or a @file/path; wins over individual flags per top-level filter path.")
@@ -8557,14 +8700,15 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--estimate", "Run a free server-side preflight pass: resolves provider enums and a free count probe for an estimated match count (zero credits).")
         .option("--materialize-preview", "Create a preview table with route rows.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("companies search plan", options, () => requestOxygen("/api/cli/companies/search/plan", {
             method: "POST",
-            body: readCompaniesSearchPlanBody(options),
+            body: readCompaniesSearchPlanBody(options, promptArg),
         }));
     }))
         .addCommand(new Command("run")
         .description("Return a dry-run request or queue a live company-search ingestion run.")
+        .argument("[prompt]", "Prompt text or @file (same as --prompt). The --prompt flag wins if both are given.")
         .option("--prompt <text-or-file>", "Company-search prompt, or a path to a prompt file.")
         .option("--plan-json <json-or-file>", "Plan JSON returned by companies search plan, or a path to a JSON file.")
         .option("--route-id <id>", "Route id from the plan to execute.")
@@ -8592,10 +8736,10 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--estimate", "Run a free server-side preflight pass when planning from --prompt: resolves provider enums and a free count probe (zero credits).")
         .option("--approved", "Required for live runs after inspecting dry-run output.")
         .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
+        .action(async (promptArg, options) => {
         await handleAsyncAction("companies search run", options, () => requestOxygen("/api/cli/companies/search/run", {
             method: "POST",
-            body: readCompaniesSearchRunBody(options),
+            body: readCompaniesSearchRunBody(options, promptArg),
         }));
     })))
         .addCommand(new Command("enrich")
@@ -9311,6 +9455,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .description("Board of the PRIMARY managed external data providers (enrichment, people/company search, web search, scraping, signals, AI-column web grounding, LLM inference): per provider health probe, 7d traffic, balance, 30d/7d COGS, rate policy, spend ceilings, breaker, and posture, plus the platform runaway guards and how old each snapshot is. Reads the snapshots the crons write; --refresh re-runs those same zero-credit snapshots first. Staff only.")
         .option("--refresh", "Re-run the zero-credit snapshot work the three crons run (provider health probes, managed balances, cost snapshot) before reading the board. No paid provider call and no credit spend; takes up to a few minutes.")
         .option("--stages <csv>", "Limit --refresh to these stages: health, balances, costs. Defaults to all three.")
+        .option("--force", "Refresh even inside the server's cooldown on re-probing every managed vendor. Only with --refresh.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         const stages = readCsvOption(options.stages);
@@ -9320,6 +9465,13 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
             emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--stages only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
             return;
         }
+        if (options.force && !options.refresh) {
+            // Same reason as --stages: --force only relaxes the refresh
+            // cooldown, so on its own it reads the very board the caller
+            // believes it just forced a re-probe of.
+            emitCliFailure("admin primary-providers", new OxygenError("invalid_request", "--force only applies to --refresh. Add --refresh to re-run those snapshots.", { exitCode: 2 }));
+            return;
+        }
         let failed = false;
         const board = await requestOxygen("/api/cli/admin/primary-providers", options.refresh
             ? {
@@ -9330,7 +9482,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
                 // finishes — the operator reads a failure for work that
                 // succeeded and re-runs the outbound probes.
                 timeoutMs: 300_000,
-                body: { refresh: true, ...(stages.length > 0 ? { stages } : {}) },
+                body: {
+                    refresh: true,
+                    ...(stages.length > 0 ? { stages } : {}),
+                    ...(options.force ? { force: true } : {}),
+                },
             }
             : undefined).catch((error) => {
             emitCliFailure("admin primary-providers", error);
@@ -10455,11 +10611,20 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--return <mode>", "Legacy response shape: raw, compact, or summary. Defaults to raw.")
         .option("--return-mode <mode>", "Response shape: raw, compact, or summary. Prefer summary for large search responses.")
         .option("--oxygen-cursor <cursor>", "Short Oxygen cursor returned as oxygen_next_cursor by a previous tool run.")
-        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools.")
+        .option("--max-credits <n>", "Credit ceiling for live paid tools; not needed for no-bill tools, and 0 is accepted for no-bill operations.")
         .option("--approved", "Required for live paid tools and external writes after inspecting dry-run output.")
         .option("--json", "Print a JSON envelope.")
         .action(async (toolId, options) => {
-        const maxCredits = readPositiveNumber(options.maxCredits);
+        // Zero is a real ceiling here, not a typo: /api/cli/tools/run only
+        // demands a positive max_credits for BILLED tools, so a documented
+        // no-bill operation is legitimately run with --max-credits 0. The
+        // positive-only reader rejected that locally, before the request.
+        //
+        // Non-negative NUMBER, not readPositiveNumberOrZero (a whole seat
+        // count): this command's own dry-run hint prints "--max-credits
+        // 24.94", so an integer reader would refuse the very command the CLI
+        // just told the operator to run.
+        const maxCredits = readNonNegativeNumber(options.maxCredits);
         await handleAsyncAction("tools run", options, () => requestOxygen("/api/cli/tools/run", {
             method: "POST",
             body: {
@@ -10612,7 +10777,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .option("--linkedin-url <url>", "Company LinkedIn URL.")
         .option("--fields <fields>", "Comma-separated company fields. Defaults to domain,linkedin_url,headcount,industry.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
-        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live.")
+        .option("--max-credits <credits>", "Spend ceiling. Required for --mode live; 0 runs only the zero-credit lanes (the priced lanes are skipped as credit_ceiling_reached).")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("find company", options, () => requestOxygen("/api/cli/find/run", { method: "POST", body: buildFindBody("company", options) }));
@@ -10621,11 +10786,11 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         .command("verify")
         .description("Check whether emails you already have are safe to send to. dry_run previews the provider chain for free; live spends and needs --max-credits.")
         .addCommand(new Command("email")
-        .description("Verify one or more email addresses. MillionVerifier answers first; addresses on catch-all (accept-all) domains, which it can only flag as risky, escalate automatically to BounceBan to get a real answer. Returns valid / invalid / catch_all / unknown per address.")
+        .description("Verify one or more email addresses. MillionVerifier answers first; addresses on catch-all (accept-all) domains, which it can only flag as risky, escalate automatically to BounceBan to get a real answer. Returns valid / invalid / catch_all / unknown per address. An address whose escalation could not run keeps catch_all — record it as unconfirmed, never verified — and its escalation_unavailable_reason plus next_action say why and what to do: provider_account_dry on the managed lane is Oxygen's BounceBan balance, not your workspace credits, and you were not charged for it.")
         .argument("<emails...>", "One or more email addresses to verify.")
         .option("--mode <mode>", "dry_run (default) previews the plan and spends nothing; live spends credits and returns the answer.")
         .option("--approved", "Same as --mode live. Accepted because the global help footer names --approved as the way to authorize a credit-spending command.")
-        .option("--max-credits <credits>", "Spend ceiling for the whole run. Required for --mode live. Run the free dry_run first — it returns estimate.recommended_max_credits, the value that guarantees every catch-all address still gets escalated.")
+        .option("--max-credits <credits>", "Spend ceiling for the whole run. Required for --mode live. Run the free dry_run first — it returns estimate.recommended_max_credits, the value that guarantees every catch-all address still gets escalated. Re-verifying the exact same address in this workspace replays MillionVerifier's first pass free for up to 30 days, so a repeat run can report credits_used 0 — the catch-all escalation is never cached, and its reservation is released in full when that call returns no verdict.")
         .option("--json", "Print a JSON envelope.")
         .action(async (emails, options) => {
         await handleAsyncAction("verify email", options, () => requestOxygen("/api/cli/verify/run", {
@@ -11473,7 +11638,46 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     })));
     program.addCommand(new Command("engagement")
-        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`), and react or comment on it. Recurring capture — a post's engagers on a cadence, 'who viewed my profile', new followers, new connections — is a live table: arm it with `oxygen linkedin intent setup` and operate it with `oxygen feeds list|pause|resume|run`. For recurring competitor-profile monitoring that discovers future posts, start with `oxygen recipes list competitor --json`. Harvests run as a slow, durable drip under a conservative read budget.")
+        .description("Capture LinkedIn intent from one known post (harvest needs its public URL or the composite social_id from `oxygen posts get`), and react or comment on it. Recurring capture — a post's engagers on a cadence, 'who viewed my profile', new followers, new connections — is a live table: arm it with `oxygen linkedin intent setup` and operate it with `oxygen feeds list|pause|resume|run`. For daily monitoring across profiles and their recent post engagers, start with `oxygen tables watcher preview --help` (free credit review; one editable table). Harvests run as a slow, durable drip under a conservative read budget.")
+        .addCommand(new Command("engagers")
+        .description("Read one post's reactors and commenters right now as a de-duplicated people list ready to enroll. Pages both sources up to --max-pages (default 5, max 20) x 100 per page; `truncated: true` in the envelope means a cap stopped a source that still had more — raise --max-pages, or use `oxygen engagement harvest` for a post too big to read in one request. Nothing is sent and no credits are spent, but every page is one LinkedIn read against the sender account. --post is the composite social_id from `oxygen posts get` (NOT the activity URN).")
+        .requiredOption("--post <social_id>", "Composite post social_id from `oxygen posts get` (NOT the activity URN).")
+        .option("--account <ref>", "Sender account that reads (sender id, connection id, or Unipile account id). Omit for the org default.")
+        .option("--limit <n>", "Engagers per PAGE (default 100, which is also the provider maximum). Per source you get --limit x --max-pages.")
+        .option("--max-pages <n>", "Pages to walk per source, 1-20 (default 5, so 500 reactors + 500 commenters).")
+        .option("--no-reactions", "Skip reactors.")
+        .option("--no-comments", "Skip commenters.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        await handleAsyncAction("engagement engagers", options, async () => {
+            const post = readOption(options.post);
+            if (!post)
+                throw new Error("--post is required (the composite social_id from `oxygen posts get`).");
+            const account = readOption(options.account);
+            const limit = readPositiveInteger(options.limit);
+            const maxPages = readPositiveInteger(options.maxPages);
+            const params = new URLSearchParams({ post });
+            if (account)
+                params.set("account", account);
+            if (limit !== undefined)
+                params.set("limit", String(limit));
+            // Forwarded as-is: the route owns the 1-20 range so an
+            // out-of-range value fails loudly instead of silently reading
+            // fewer pages than the caller asked for.
+            if (maxPages !== undefined)
+                params.set("max_pages", String(maxPages));
+            if (options.reactions === false)
+                params.set("include_reactions", "false");
+            if (options.comments === false)
+                params.set("include_comments", "false");
+            const data = await requestOxygen(`/api/cli/linkedin/engagement?${params.toString()}`);
+            // Ahead of the payload, and only for a human: a machine caller
+            // reads truncated/partial_reason off the envelope itself.
+            if (!options.json)
+                writeEngagersReceipt(data);
+            return data;
+        });
+    }))
         .addCommand(new Command("harvest")
         .description("Start (or re-arm) a harvest of a post's engagers into a workspace table you can enroll into a sequence. Engagers drip into the table over many ticks; poll `engagement status` to watch it fill. No messages are sent. Cookieless harvests spend Oxygen credits per scraper page and require --max-credits.")
         .requiredOption("--post <social_id_or_url>", "Composite post social_id from `oxygen posts get` (NOT the activity URN), or the public LinkedIn post URL for cookieless.")
@@ -13669,18 +13873,63 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("remove")
-        .description("Remove a lead provider id from the org do-not-contact list (re-enable contact).")
-        .requiredOption("--lead <provider_id>", "The lead provider id to un-suppress.")
-        .option("--json", "Print a JSON envelope.")
-        .action(async (options) => {
-        await handleAsyncAction("suppressions remove", options, () => {
-            const lead = readOption(options.lead);
-            if (!lead)
-                throw new Error("--lead is required.");
-            return requestOxygen(`/api/cli/suppressions?lead_provider_id=${encodeURIComponent(lead)}`, {
-                method: "DELETE",
+        .description("Remove one lead provider id (--lead), or every identity of one merged person (--subject-id), from the org do-not-contact list (re-enable contact). A subject id is stamped on each identifier of an imported contact: `hubspot:contacts:<id>` from `suppressions hubspot sync`, `manual:<uuid>` returned by `suppressions import-person`. Read it as metadata.dnc_subject_id in `suppressions list` (LinkedIn rows only) or in `suppressions addresses|phones|companies --json`, which is where an email- or phone-only contact appears.")
+        .option("--lead <provider_id>", "The lead provider id to un-suppress. Mutually exclusive with --subject-id.")
+        .option("--subject-id <id>", "DNC subject id (metadata.dnc_subject_id). Clears that person's email, phone, LinkedIn, and company suppressions in one transaction.")
+        .option("--json", "Print a JSON envelope.")
+        .action(async (options) => {
+        const subjectId = readOption(options.subjectId);
+        if (!subjectId) {
+            await handleAsyncAction("suppressions remove", options, () => {
+                const lead = readOption(options.lead);
+                if (!lead)
+                    throw new Error("Pass --lead <provider_id> or --subject-id <id>.");
+                return requestOxygen(`/api/cli/suppressions?lead_provider_id=${encodeURIComponent(lead)}`, {
+                    method: "DELETE",
+                });
             });
-        });
+            return;
+        }
+        try {
+            if (readOption(options.lead)) {
+                throw new Error("Pass either --lead or --subject-id, not both.");
+            }
+            const data = await requestOxygen(`/api/cli/suppressions?subject_id=${encodeURIComponent(subjectId)}`, { method: "DELETE" });
+            if (options.json) {
+                writeJson(success("suppressions remove", data));
+            }
+            else {
+                // Same compact multi-ledger receipt style as `suppressions import`:
+                // the per-channel counts plus up to 10 cleared identifiers (the full
+                // list is always in the --json envelope).
+                const parsed = (data ?? {});
+                const identities = Array.isArray(parsed.removed_identities) ? parsed.removed_identities : [];
+                const removedCount = parsed.removed_count ?? 0;
+                writeJson({
+                    subject_id: parsed.subject_id ?? subjectId,
+                    removed_count: removedCount,
+                    removed_emails: parsed.removed?.email ?? 0,
+                    removed_phones: parsed.removed?.phone ?? 0,
+                    removed_linkedin: parsed.removed?.linkedin ?? 0,
+                    removed_companies: parsed.removed?.company ?? 0,
+                    removed_identities: identities.slice(0, 10),
+                    // Counted off removed_count, not the echoed array: the API caps
+                    // that list too, so --json is NOT a way to see the rest. The
+                    // counts above are the exact record of what was cleared.
+                    ...(removedCount > Math.min(identities.length, 10)
+                        ? {
+                            removed_identities_note: `Showing ${Math.min(identities.length, 10)} of ${removedCount} cleared identifiers; the counts above are exact.`,
+                        }
+                        : {}),
+                    ...(parsed.note ? { note: parsed.note } : {}),
+                    deep_link: parsed.deepLink,
+                });
+            }
+            writeCreditsReceipt(data);
+        }
+        catch (error) {
+            emitCliFailure("suppressions remove", error);
+        }
     }))
         .addCommand(new Command("import")
         .description("Bulk-import a do-not-contact blocklist from a file (newline / comma / whitespace separated, max 5000). An entry with '@' goes on the per-address email list; a bare domain (e.g. acme.com) blocks email to that whole domain; a LinkedIn profile URL or member id (ACo...) lands on the people do-not-contact list; any other URL is rejected. A domain block is a sharp tool, so --reason is REQUIRED when the file contains any domains; otherwise manual is the default. Idempotent. Consumes 0 credits.")
@@ -13776,6 +14025,12 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("import-person")
+        // Deliberately NOT extended with the subjects[] pointer: this help text
+        // is already 199 chars, and the generated CLI reference cell truncates a
+        // description past 200 to its FIRST sentence — appending anything drops
+        // the "domain is company-wide, never inferred from --email" warning from
+        // the public table. The receipt itself carries `subjects[]`, and
+        // `suppressions remove --help` names where subject ids come from.
         .description("Import one person as one DNC subject with any combination of email, LinkedIn, E.164 phone, and an explicitly supplied company domain. The domain is company-wide and is never inferred from --email.")
         .option("--name <name>", "Optional contact display name.")
         .option("--email <address>", "Email address to suppress.")
@@ -14276,7 +14531,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
     program.addCommand(new Command("mailboxes")
         .description("Native email sending pool: register/refresh Google/Microsoft mailboxes (including secure local credential-file transfer), pause/disable inboxes, connect EmailGuard monitoring, and inspect/control OXYGEN Warm-up. Fresh managed InboxKit Google/Microsoft/Azure orders activate exact-scope warm-up automatically after provisioning under their approved default-on add-on. Google reuses the managed credential just in time; Microsoft/Azure uses native export. Standalone warm-up plans and credit caps are for BYOK/imported mailboxes, managed opt-outs, or later separate enrollment. OXYGEN Warm-up never owns campaign dispatch. Safe import preflight: run `oxygen mailboxes compatibility --catalog-only --json`, then `oxygen mailboxes import --file <path> --validate-only --json` (add the credential source flags shown by import help when the file contains credentials).")
         .addCommand(new Command("list")
-        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). Read each mailbox's warmupTruth for warm-up (state, last_send, pause, dispatch, next_action with the exact command); warmupState is only the stored rail token and reads `error` for a provider-paused seat. mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`.")
+        .description("List the org's sending mailboxes with provider, status, warmup state, source (managed = bought through Oxygen, byok = bring-your-own), worker-owned connectionRepair and warmupRepair state, and a pool overview (including counts by source). Read each mailbox's warmupTruth for warm-up (state, last_send, pause, dispatch, next_action with the exact command); warmupState is only the stored rail token and reads `error` for a provider-paused seat. mode=automatic means OXYGEN owns the next bounded retry — do not ask for browser consent or disable/re-enable an existing warm-up seat. To see only Google/Microsoft mailboxes that still need OAuth connection, including attempt budgets and manual remedies, use `oxygen mailboxes oauth-health --json`. Read the fleet from `summary` — `summary.by_warmup`, `by_status`, `by_provider`, `by_auth_mode`, `by_transport`, and `by_source` already aggregate every mailbox, so you never need to iterate the `mailboxes` array to count them.")
         .option("--status <status>", "Filter by status: active, paused, disabled, or provisioning (ordered, still being set up).")
         .option("--tag <tags>", "Comma-separated workspace tags — matches mailboxes carrying ANY of these tags (see `oxygen tags list`).")
         .option("--json", "Print a JSON envelope.")
@@ -14330,7 +14585,7 @@ fixed scan; watermark_cursor starts a later bounded replay. Consumers must retai
         });
     }))
         .addCommand(new Command("health")
-        .description("Fleet email-health: the sending pool rolled up by external deliverability reputation (healthy/degraded/critical/unknown), per-mailbox scores, connected health providers, and DIRECTIONAL recommendations. Pure read — 0 credits; never pauses a mailbox.")
+        .description("Fleet email-health: the sending pool rolled up by external deliverability reputation (healthy/degraded/critical/unknown), per-mailbox scores, connected health providers, and DIRECTIONAL recommendations — plus OXYGEN's OWN evidence for the last 7 days, which needs no provider connected: the bounce notifications each mailbox received classified as provider rejection / dead address / mailbox full / delay (a Gmail reputation block shows up as provider_rejected), distinct recipients that first hard-bounced, sequence sends OXYGEN logged (source=sequence only), warm-up day, health score and stop cause, the advisory daily cap that warm-up age supports, and the same rollup per sending domain ranked worst-first. Notifications whose body was never stored count as signals.dsn7d.unclassified, which means OXYGEN could not look — not that nothing was wrong. Read health_coverage to see how many mailboxes an external provider has actually scored. Start from the two fleet reads instead of scanning the mailbox array: warmup.byCause (why warm-up stopped, counted once for the whole pool) and signals.capOverRecommendedMailboxes (mailboxes whose configured cap is above the one warm-up supports — per mailbox, compare dailyCap with recommendedDailyCap; the gap is flagged as the cap_exceeds_readiness warning). Every count is scoped, and the scope is stamped into the payload as signals.window (7d) and signals.sendSource (sequence sends only), on the fleet object and on every mailbox: a 0 means nothing was recorded in that window for that send source, NOT that the fleet is un-blocklisted everywhere. Pure read — 0 credits; never pauses a mailbox or changes a cap.")
         .option("--json", "Print a JSON envelope.")
         .action(async (options) => {
         await handleAsyncAction("mailboxes health", options, () => requestOxygen("/api/cli/mailboxes/health"));
@@ -18453,11 +18708,15 @@ function readFeedBindBody(table, options) {
         ...(options.approved ? { approved: true } : {}),
     };
 }
-function readSignalsSearchPlanBody(options) {
+function readSignalsSearchPlanBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
     const targetCount = readPositiveInt(options.targetCount);
     const filters = readSignalSearchFilters(options);
     return {
-        prompt: readFileIfPresent(options.prompt),
+        // Omit when neither was given so the request still reaches the server, which
+        // answers with a clean `prompt is required.` instead of crashing readFileIfPresent.
+        ...(promptSource !== undefined ? { prompt: readFileIfPresent(promptSource) } : {}),
         family: options.family,
         ...(readOption(options.scope) ? { scope: readOption(options.scope) } : {}),
         ...(targetCount !== undefined ? { target_count: targetCount } : {}),
@@ -18465,8 +18724,10 @@ function readSignalsSearchPlanBody(options) {
         ...(options.estimate ? { estimate: true } : {}),
     };
 }
-function readSignalsSearchRunBody(options) {
-    const prompt = options.prompt ? readFileIfPresent(options.prompt) : null;
+function readSignalsSearchRunBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const prompt = promptSource ? readFileIfPresent(promptSource) : null;
     const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
     if (!prompt && !plan) {
         throw new OxygenError("invalid_request", "Pass --prompt or --plan-json.", { exitCode: 1 });
@@ -18538,11 +18799,15 @@ function readSignalSearchFilters(options) {
     }
     return Object.keys(filters).length > 0 ? filters : null;
 }
-function readCompaniesSearchPlanBody(options) {
+function readCompaniesSearchPlanBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
     const targetCount = readPositiveInt(options.targetCount);
     const filters = readCompanySearchFilters(options);
     return {
-        prompt: readFileIfPresent(options.prompt),
+        // Omit when neither was given so the request still reaches the server, which
+        // answers with a clean `prompt is required.` instead of crashing readFileIfPresent.
+        ...(promptSource !== undefined ? { prompt: readFileIfPresent(promptSource) } : {}),
         ...(targetCount !== undefined ? { target_count: targetCount } : {}),
         ...(options.sourceIntent ? { source_intent: options.sourceIntent } : {}),
         ...(filters ? { filters } : {}),
@@ -18550,8 +18815,10 @@ function readCompaniesSearchPlanBody(options) {
         ...(options.materializePreview ? { materialize_preview: true } : {}),
     };
 }
-function readCompaniesSearchRunBody(options) {
-    const prompt = options.prompt ? readFileIfPresent(options.prompt) : null;
+function readCompaniesSearchRunBody(options, promptArg) {
+    // The prompt may arrive as --prompt or as the positional argument; the flag wins.
+    const promptSource = options.prompt ?? promptArg;
+    const prompt = promptSource ? readFileIfPresent(promptSource) : null;
     const plan = options.planJson ? readSearchPlanJson(options.planJson) : null;
     if (!prompt && !plan) {
         throw new OxygenError("invalid_request", "Pass --prompt or --plan-json.", { exitCode: 1 });
@@ -24341,6 +24608,27 @@ function readPositiveNumber(value) {
     }
     return parsed;
 }
+/**
+ * A spend ceiling where ZERO IS VALID and meaningful: `find company
+ * --max-credits 0` asks for the lanes that cost nothing (crustdata's identify
+ * lane resolves domain↔LinkedIn for 0 credits) and skips every priced one.
+ * readPositiveNumber rejected it client-side, so the free lanes were
+ * unreachable from the CLI at all (Plain T-111). Fractional ceilings stay legal
+ * — lane estimates are fractional — so this is not the whole-number reader.
+ */
+function readCreditCeilingOrZero(value) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    const parsed = Number(trimmed);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new OxygenError("invalid_number", "Expected a number of 0 or more.", {
+            details: { value },
+            exitCode: 1,
+        });
+    }
+    return parsed;
+}
 /**
  * A whole count (days, rows, windows). Its positive-number sibling accepts 2.5,
  * which for a scan bound is always a typo — rejected here so it costs no round trip,