autotouch-cli 0.2.6__tar.gz → 0.2.8__tar.gz

{autotouch_cli-0.2.6 → autotouch_cli-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.6
+Version: 0.2.8
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -218,7 +218,7 @@ autotouch jobs get --job-id <JOB_ID>
 
 ## Safe run patterns (`firstN` + `--unprocessed-only`)
 
-Use this pattern to avoid paying twice for the same top rows.
+Use this pattern for progressive rollouts.
 
 ```bash
 # Pilot first 10 rows
@@ -244,9 +244,74 @@ autotouch columns run \
 
 Notes:
 - `firstN` without `--unprocessed-only` can re-run already-processed rows.
+- With `--unprocessed-only`, `firstN` means "first N currently eligible unprocessed rows", not "exactly N new rows since your last check".
+- If you need an exact count (for example exactly 5 rows), use `run-next` below.
 - `--wait` polls `/api/bulk-jobs/{job_id}` until terminal status.
 - If a job stays `queued`, workers for that provider queue may be scaled to `0`.
 
+## Exact count runs (`run-next`)
+
+Use this when you need exactly `N` rows in one run.
+The CLI selects candidate row IDs first, then executes `/run` with `scope=subset`.
+
+```bash
+# Run exactly 5 unprocessed rows from the current view
+autotouch columns run-next \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --count 5 \
+  --filters-file filters.json \
+  --show-estimate \
+  --wait
+```
+
+Notes:
+- Default behavior is unprocessed-only selection.
+- Add `--include-processed` to allow already-processed rows into candidate selection.
+- `run-next` is deterministic on count (subject to available eligible rows).
+- If fewer than `N` eligible rows exist, it runs the available subset and reports selected count.
+
+### Agent execution contract (strict)
+
+When operating this CLI as an agent, use backend job state as source of truth:
+
+1. Treat a run as started only if `/run` returns a `jobId` (`job_id`).
+2. Treat a run as completed only when `GET /api/bulk-jobs/{job_id}` returns terminal status.
+3. Never infer progress/completion from local process liveness alone.
+4. If polling is blocked by local network/approval/sandbox constraints, report "run state not confirmed" (do not claim still running/completed).
+
+Terminal status values:
+
+- `completed`
+- `partial`
+- `error`
+- `cancelled`
+
+Non-terminal status values:
+
+- `queued`
+- `distributing`
+- `processing`
+
+### Canonical fallback (when `--wait` is noisy in your runtime)
+
+```bash
+# 1) Queue run and capture jobId
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 15 \
+  --unprocessed-only \
+  --show-estimate \
+  --output json
+
+# 2) Poll backend truth directly
+autotouch jobs get --job-id <JOB_ID> --output json
+```
+
+Repeat `jobs get` until status is terminal.
+
 ## CSV import (agent-safe, async-first)
 
 `rows import-csv` defaults to optimized import transport (`/import-optimized`) so large files do not fail on a single long request.

{autotouch_cli-0.2.6 → autotouch_cli-0.2.8}/autotouch_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.6
+Version: 0.2.8
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -218,7 +218,7 @@ autotouch jobs get --job-id <JOB_ID>
 
 ## Safe run patterns (`firstN` + `--unprocessed-only`)
 
-Use this pattern to avoid paying twice for the same top rows.
+Use this pattern for progressive rollouts.
 
 ```bash
 # Pilot first 10 rows
@@ -244,9 +244,74 @@ autotouch columns run \
 
 Notes:
 - `firstN` without `--unprocessed-only` can re-run already-processed rows.
+- With `--unprocessed-only`, `firstN` means "first N currently eligible unprocessed rows", not "exactly N new rows since your last check".
+- If you need an exact count (for example exactly 5 rows), use `run-next` below.
 - `--wait` polls `/api/bulk-jobs/{job_id}` until terminal status.
 - If a job stays `queued`, workers for that provider queue may be scaled to `0`.
 
+## Exact count runs (`run-next`)
+
+Use this when you need exactly `N` rows in one run.
+The CLI selects candidate row IDs first, then executes `/run` with `scope=subset`.
+
+```bash
+# Run exactly 5 unprocessed rows from the current view
+autotouch columns run-next \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --count 5 \
+  --filters-file filters.json \
+  --show-estimate \
+  --wait
+```
+
+Notes:
+- Default behavior is unprocessed-only selection.
+- Add `--include-processed` to allow already-processed rows into candidate selection.
+- `run-next` is deterministic on count (subject to available eligible rows).
+- If fewer than `N` eligible rows exist, it runs the available subset and reports selected count.
+
+### Agent execution contract (strict)
+
+When operating this CLI as an agent, use backend job state as source of truth:
+
+1. Treat a run as started only if `/run` returns a `jobId` (`job_id`).
+2. Treat a run as completed only when `GET /api/bulk-jobs/{job_id}` returns terminal status.
+3. Never infer progress/completion from local process liveness alone.
+4. If polling is blocked by local network/approval/sandbox constraints, report "run state not confirmed" (do not claim still running/completed).
+
+Terminal status values:
+
+- `completed`
+- `partial`
+- `error`
+- `cancelled`
+
+Non-terminal status values:
+
+- `queued`
+- `distributing`
+- `processing`
+
+### Canonical fallback (when `--wait` is noisy in your runtime)
+
+```bash
+# 1) Queue run and capture jobId
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 15 \
+  --unprocessed-only \
+  --show-estimate \
+  --output json
+
+# 2) Poll backend truth directly
+autotouch jobs get --job-id <JOB_ID> --output json
+```
+
+Repeat `jobs get` until status is terminal.
+
 ## CSV import (agent-safe, async-first)
 
 `rows import-csv` defaults to optimized import transport (`/import-optimized`) so large files do not fail on a single long request.

{autotouch_cli-0.2.6 → autotouch_cli-0.2.8}/docs/research-table/reference/autotouch-cli.md

@@ -209,7 +209,7 @@ autotouch jobs get --job-id <JOB_ID>
 
 ## Safe run patterns (`firstN` + `--unprocessed-only`)
 
-Use this pattern to avoid paying twice for the same top rows.
+Use this pattern for progressive rollouts.
 
 ```bash
 # Pilot first 10 rows
@@ -235,9 +235,74 @@ autotouch columns run \
 
 Notes:
 - `firstN` without `--unprocessed-only` can re-run already-processed rows.
+- With `--unprocessed-only`, `firstN` means "first N currently eligible unprocessed rows", not "exactly N new rows since your last check".
+- If you need an exact count (for example exactly 5 rows), use `run-next` below.
 - `--wait` polls `/api/bulk-jobs/{job_id}` until terminal status.
 - If a job stays `queued`, workers for that provider queue may be scaled to `0`.
 
+## Exact count runs (`run-next`)
+
+Use this when you need exactly `N` rows in one run.
+The CLI selects candidate row IDs first, then executes `/run` with `scope=subset`.
+
+```bash
+# Run exactly 5 unprocessed rows from the current view
+autotouch columns run-next \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --count 5 \
+  --filters-file filters.json \
+  --show-estimate \
+  --wait
+```
+
+Notes:
+- Default behavior is unprocessed-only selection.
+- Add `--include-processed` to allow already-processed rows into candidate selection.
+- `run-next` is deterministic on count (subject to available eligible rows).
+- If fewer than `N` eligible rows exist, it runs the available subset and reports selected count.
+
+### Agent execution contract (strict)
+
+When operating this CLI as an agent, use backend job state as source of truth:
+
+1. Treat a run as started only if `/run` returns a `jobId` (`job_id`).
+2. Treat a run as completed only when `GET /api/bulk-jobs/{job_id}` returns terminal status.
+3. Never infer progress/completion from local process liveness alone.
+4. If polling is blocked by local network/approval/sandbox constraints, report "run state not confirmed" (do not claim still running/completed).
+
+Terminal status values:
+
+- `completed`
+- `partial`
+- `error`
+- `cancelled`
+
+Non-terminal status values:
+
+- `queued`
+- `distributing`
+- `processing`
+
+### Canonical fallback (when `--wait` is noisy in your runtime)
+
+```bash
+# 1) Queue run and capture jobId
+autotouch columns run \
+  --table-id <TABLE_ID> \
+  --column-id <COLUMN_ID> \
+  --scope firstN \
+  --first-n 15 \
+  --unprocessed-only \
+  --show-estimate \
+  --output json
+
+# 2) Poll backend truth directly
+autotouch jobs get --job-id <JOB_ID> --output json
+```
+
+Repeat `jobs get` until status is terminal.
+
 ## CSV import (agent-safe, async-first)
 
 `rows import-csv` defaults to optimized import transport (`/import-optimized`) so large files do not fail on a single long request.

{autotouch_cli-0.2.6 → autotouch_cli-0.2.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "autotouch-cli"
-version = "0.2.6"
+version = "0.2.8"
 description = "Autotouch Smart Table CLI"
 readme = "docs/research-table/reference/autotouch-cli.md"
 requires-python = ">=3.9"

{autotouch_cli-0.2.6 → autotouch_cli-0.2.8}/scripts/smart_table_cli.py

@@ -604,6 +604,304 @@ def _normalize_run_payload(args: argparse.Namespace) -> Dict[str, Any]:
     return payload
 
 
+def _resolve_column_key(
+    *,
+    table_id: str,
+    column_id: str,
+    base_url: str,
+    token: str,
+    use_x_api_key: bool,
+    timeout: int,
+    verbose: bool,
+) -> str:
+    columns_raw = _request_api(
+        "GET",
+        f"/api/tables/{table_id}/columns",
+        base_url=base_url,
+        token=token,
+        use_x_api_key=use_x_api_key,
+        timeout=timeout,
+        verbose=verbose,
+    )
+    if isinstance(columns_raw, list):
+        columns = columns_raw
+    elif isinstance(columns_raw, dict):
+        columns = columns_raw.get("columns") or columns_raw.get("items") or columns_raw.get("data") or []
+    else:
+        columns = []
+
+    target = str(column_id)
+    for col in columns:
+        if not isinstance(col, dict):
+            continue
+        cid = str(col.get("id") or col.get("_id") or "")
+        if cid != target:
+            continue
+        key = str(col.get("key") or "").strip()
+        if key:
+            return key
+        break
+
+    print(f"ERROR: failed to resolve column key for column_id={column_id}", file=sys.stderr)
+    sys.exit(1)
+
+
+def _is_processed_cell_value(value: Any) -> bool:
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return value.strip() != ""
+    if isinstance(value, (list, tuple, set, dict)):
+        return len(value) > 0
+    return True
+
+
+def _select_next_row_ids(
+    *,
+    table_id: str,
+    column_id: str,
+    count: int,
+    filters: Optional[Dict[str, Any]],
+    unprocessed_only: bool,
+    page_size: int,
+    base_url: str,
+    token: str,
+    use_x_api_key: bool,
+    timeout: int,
+    verbose: bool,
+) -> Dict[str, Any]:
+    if count <= 0:
+        return {"row_ids": [], "requested": 0, "selected": 0, "scanned_rows": 0}
+
+    column_key = _resolve_column_key(
+        table_id=table_id,
+        column_id=column_id,
+        base_url=base_url,
+        token=token,
+        use_x_api_key=use_x_api_key,
+        timeout=timeout,
+        verbose=verbose,
+    )
+
+    selected: List[str] = []
+    seen: set[str] = set()
+    scanned_rows = 0
+    page_count = 0
+    cursor: Optional[str] = None
+
+    effective_page_size = max(1, min(int(page_size or 200), 1000))
+    filters_payload = filters if isinstance(filters, dict) else None
+
+    while len(selected) < count:
+        page_count += 1
+        params: Dict[str, Any] = {"page_size": effective_page_size}
+        if cursor:
+            params["cursor"] = cursor
+        if filters_payload:
+            params["filters"] = json.dumps(filters_payload, separators=(",", ":"))
+
+        page = _request_api(
+            "GET",
+            f"/api/tables/{table_id}/rows",
+            base_url=base_url,
+            token=token,
+            use_x_api_key=use_x_api_key,
+            params=params,
+            timeout=timeout,
+            verbose=verbose,
+        )
+        if not isinstance(page, dict):
+            print(f"ERROR: unexpected rows response: {page}", file=sys.stderr)
+            sys.exit(1)
+
+        rows = page.get("rows") or []
+        if not isinstance(rows, list):
+            print(f"ERROR: rows payload is not a list: {type(rows).__name__}", file=sys.stderr)
+            sys.exit(1)
+
+        for row in rows:
+            if not isinstance(row, dict):
+                continue
+            scanned_rows += 1
+            row_id = str(row.get("_id") or row.get("id") or row.get("rowId") or "").strip()
+            if not row_id or row_id in seen:
+                continue
+            seen.add(row_id)
+
+            if unprocessed_only and _is_processed_cell_value(row.get(column_key)):
+                continue
+
+            selected.append(row_id)
+            if len(selected) >= count:
+                break
+
+        has_more = bool(page.get("hasMore") if "hasMore" in page else page.get("has_more"))
+        next_cursor = page.get("nextCursor") if page.get("nextCursor") is not None else page.get("next_cursor")
+        if len(selected) >= count:
+            break
+        if not has_more or not next_cursor:
+            break
+        cursor = str(next_cursor)
+
+    return {
+        "row_ids": selected,
+        "requested": int(count),
+        "selected": len(selected),
+        "scanned_rows": scanned_rows,
+        "pages_scanned": page_count,
+        "column_key": column_key,
+        "used_filters": bool(filters_payload),
+        "unprocessed_only": bool(unprocessed_only),
+    }
+
+
+def _execute_run_flow(
+    *,
+    args: argparse.Namespace,
+    token: str,
+    payload: Dict[str, Any],
+    context: Optional[Dict[str, Any]] = None,
+) -> None:
+    estimate_data: Optional[Dict[str, Any]] = None
+    should_estimate = bool(args.show_estimate or args.max_credits is not None or args.dry_run)
+    if should_estimate:
+        estimate_raw = _request_api(
+            "POST",
+            f"/api/tables/{args.table_id}/columns/{args.column_id}/estimate",
+            base_url=args.base_url,
+            token=token,
+            use_x_api_key=args.use_x_api_key,
+            payload=payload,
+            timeout=args.timeout,
+            verbose=args.verbose,
+        )
+        if not isinstance(estimate_raw, dict):
+            print(f"ERROR: unexpected estimate response: {estimate_raw}", file=sys.stderr)
+            sys.exit(1)
+        estimate_data = estimate_raw
+
+    if args.max_credits is not None:
+        if estimate_data is None:
+            print("ERROR: failed to compute estimate for --max-credits guard", file=sys.stderr)
+            sys.exit(1)
+        limit = float(args.max_credits)
+        estimated_max = estimate_data.get("estimated_credits_max")
+        estimated_min = float(estimate_data.get("estimated_credits_min") or 0.0)
+
+        if estimated_max is None and not bool(args.allow_unknown_max):
+            output = {
+                "blocked": True,
+                "reason": "estimated_credits_max is unknown; pass --allow-unknown-max to proceed",
+                "max_credits_limit": limit,
+                "estimate": estimate_data,
+            }
+            if context is not None:
+                output["context"] = context
+            _print_json(output, compact=args.compact)
+            sys.exit(3)
+
+        compare_value = float(estimated_max if estimated_max is not None else estimated_min)
+        if compare_value > limit:
+            output = {
+                "blocked": True,
+                "reason": "estimated credits exceed max-credits limit",
+                "max_credits_limit": limit,
+                "estimate_compare_value": compare_value,
+                "estimate": estimate_data,
+            }
+            if context is not None:
+                output["context"] = context
+            _print_json(output, compact=args.compact)
+            sys.exit(3)
+
+    if args.dry_run:
+        output = {
+            "dry_run": True,
+            "run_payload": payload,
+            "estimate": estimate_data,
+        }
+        if context is not None:
+            output["context"] = context
+        _print_json(output, compact=args.compact)
+        return
+
+    run_data = _request_api(
+        "POST",
+        f"/api/tables/{args.table_id}/columns/{args.column_id}/run",
+        base_url=args.base_url,
+        token=token,
+        use_x_api_key=args.use_x_api_key,
+        payload=payload,
+        timeout=args.timeout,
+        verbose=args.verbose,
+    )
+    if not isinstance(run_data, dict):
+        output_non_dict: Any = run_data
+        if context is not None:
+            output_non_dict = {"context": context, "run": run_data}
+        _print_json(output_non_dict, compact=args.compact)
+        return
+
+    if args.wait:
+        job_id = run_data.get("job_id") or run_data.get("jobId")
+        if not job_id:
+            print("ERROR: run response missing job_id; cannot wait", file=sys.stderr)
+            output = run_data if context is None else {"context": context, "run": run_data}
+            _print_json(output, compact=args.compact)
+            sys.exit(1)
+        if not args.quiet_wait:
+            _print_json(
+                {
+                    "job_id": str(job_id),
+                    "status": "polling_started",
+                    "hint": "polling /api/bulk-jobs/{job_id}",
+                },
+                compact=args.compact,
+            )
+
+        poll_result = _poll_job(
+            job_id=str(job_id),
+            base_url=args.base_url,
+            token=token,
+            use_x_api_key=args.use_x_api_key,
+            interval_seconds=int(args.poll_interval or 2),
+            wait_timeout_seconds=int(args.wait_timeout or 0),
+            request_timeout_seconds=int(args.timeout or DEFAULT_TIMEOUT_SECONDS),
+            verbose=args.verbose,
+            compact=args.compact,
+            once=False,
+            print_updates=not args.quiet_wait,
+        )
+        final_job = poll_result.get("job") or {}
+        timed_out = bool(poll_result.get("timed_out"))
+        output = {
+            "run": run_data,
+            "estimate": estimate_data if args.show_estimate or args.max_credits is not None else None,
+            "final_job": final_job,
+            "timed_out": timed_out,
+            "polls": int(poll_result.get("polls") or 0),
+        }
+        if context is not None:
+            output["context"] = context
+        _print_json(output, compact=args.compact)
+
+        if timed_out:
+            sys.exit(4)
+        final_status = str((final_job or {}).get("status") or "").lower()
+        if args.fail_on_error and final_status in {"error", "cancelled"}:
+            sys.exit(1)
+        if args.fail_on_partial and final_status == "partial":
+            sys.exit(1)
+        return
+
+    output_any: Any = run_data
+    if estimate_data is not None and args.show_estimate:
+        output_any = {"estimate": estimate_data, "run": run_data}
+    if context is not None:
+        output_any = {"context": context, "result": output_any}
+    _print_json(output_any, compact=args.compact)
+
+
 def _create_rows_and_patch_records(
     *,
     table_id: str,
@@ -1720,132 +2018,61 @@ def cmd_columns_projections(args: argparse.Namespace) -> None:
 def cmd_columns_run(args: argparse.Namespace) -> None:
     token = _resolve_token(args.token, required=True)
     payload = _normalize_run_payload(args)
-    estimate_data: Optional[Dict[str, Any]] = None
-    should_estimate = bool(args.show_estimate or args.max_credits is not None or args.dry_run)
-    if should_estimate:
-        estimate_raw = _request_api(
-            "POST",
-            f"/api/tables/{args.table_id}/columns/{args.column_id}/estimate",
-            base_url=args.base_url,
-            token=token,
-            use_x_api_key=args.use_x_api_key,
-            payload=payload,
-            timeout=args.timeout,
-            verbose=args.verbose,
-        )
-        if not isinstance(estimate_raw, dict):
-            print(f"ERROR: unexpected estimate response: {estimate_raw}", file=sys.stderr)
-            sys.exit(1)
-        estimate_data = estimate_raw
+    _execute_run_flow(args=args, token=token, payload=payload, context=None)
 
-    if args.max_credits is not None:
-        if estimate_data is None:
-            print("ERROR: failed to compute estimate for --max-credits guard", file=sys.stderr)
-            sys.exit(1)
-        limit = float(args.max_credits)
-        estimated_max = estimate_data.get("estimated_credits_max")
-        estimated_min = float(estimate_data.get("estimated_credits_min") or 0.0)
 
-        if estimated_max is None and not bool(args.allow_unknown_max):
-            output = {
-                "blocked": True,
-                "reason": "estimated_credits_max is unknown; pass --allow-unknown-max to proceed",
-                "max_credits_limit": limit,
-                "estimate": estimate_data,
-            }
-            _print_json(output, compact=args.compact)
-            sys.exit(3)
-
-        compare_value = float(estimated_max if estimated_max is not None else estimated_min)
-        if compare_value > limit:
-            output = {
-                "blocked": True,
-                "reason": "estimated credits exceed max-credits limit",
-                "max_credits_limit": limit,
-                "estimate_compare_value": compare_value,
-                "estimate": estimate_data,
-            }
-            _print_json(output, compact=args.compact)
-            sys.exit(3)
+def cmd_columns_run_next(args: argparse.Namespace) -> None:
+    token = _resolve_token(args.token, required=True)
+    requested_count = int(args.count or 0)
+    if requested_count <= 0:
+        print("ERROR: --count must be > 0", file=sys.stderr)
+        sys.exit(2)
 
-    if args.dry_run:
-        _print_json(
-            {
-                "dry_run": True,
-                "run_payload": payload,
-                "estimate": estimate_data,
-            },
-            compact=args.compact,
-        )
-        return
+    filters = _load_json_input(
+        inline_json=getattr(args, "filters_json", None),
+        file_path=getattr(args, "filters_file", None),
+        context="filters",
+        default=None,
+    )
+    if filters is not None and not isinstance(filters, dict):
+        print("ERROR: filters payload must be a JSON object", file=sys.stderr)
+        sys.exit(2)
 
-    run_data = _request_api(
-        "POST",
-        f"/api/tables/{args.table_id}/columns/{args.column_id}/run",
+    selection = _select_next_row_ids(
+        table_id=args.table_id,
+        column_id=args.column_id,
+        count=requested_count,
+        filters=filters,
+        unprocessed_only=bool(args.unprocessed_only),
+        page_size=int(args.page_size or 200),
         base_url=args.base_url,
         token=token,
         use_x_api_key=args.use_x_api_key,
-        payload=payload,
         timeout=args.timeout,
         verbose=args.verbose,
     )
-    if not isinstance(run_data, dict):
-        _print_json(run_data, compact=args.compact)
-        return
-
-    if args.wait:
-        job_id = run_data.get("job_id") or run_data.get("jobId")
-        if not job_id:
-            print("ERROR: run response missing job_id; cannot wait", file=sys.stderr)
-            _print_json(run_data, compact=args.compact)
-            sys.exit(1)
-        if not args.quiet_wait:
-            _print_json(
-                {
-                    "job_id": str(job_id),
-                    "status": "polling_started",
-                    "hint": "polling /api/bulk-jobs/{job_id}",
-                },
-                compact=args.compact,
-            )
-
-        poll_result = _poll_job(
-            job_id=str(job_id),
-            base_url=args.base_url,
-            token=token,
-            use_x_api_key=args.use_x_api_key,
-            interval_seconds=int(args.poll_interval or 2),
-            wait_timeout_seconds=int(args.wait_timeout or 0),
-            request_timeout_seconds=int(args.timeout or DEFAULT_TIMEOUT_SECONDS),
-            verbose=args.verbose,
-            compact=args.compact,
-            once=False,
-            print_updates=not args.quiet_wait,
-        )
-        final_job = poll_result.get("job") or {}
-        timed_out = bool(poll_result.get("timed_out"))
+    row_ids = selection.get("row_ids") or []
+    if not row_ids:
         output = {
-            "run": run_data,
-            "estimate": estimate_data if args.show_estimate or args.max_credits is not None else None,
-            "final_job": final_job,
-            "timed_out": timed_out,
-            "polls": int(poll_result.get("polls") or 0),
+            "queued": False,
+            "reason": "no eligible rows found for run-next selection",
+            "selection": selection,
         }
         _print_json(output, compact=args.compact)
-
-        if timed_out:
-            sys.exit(4)
-        final_status = str((final_job or {}).get("status") or "").lower()
-        if args.fail_on_error and final_status in {"error", "cancelled"}:
-            sys.exit(1)
-        if args.fail_on_partial and final_status == "partial":
-            sys.exit(1)
+        if args.fail_if_empty:
+            sys.exit(3)
         return
 
-    output: Any = run_data
-    if estimate_data is not None and args.show_estimate:
-        output = {"estimate": estimate_data, "run": run_data}
-    _print_json(output, compact=args.compact)
+    payload: Dict[str, Any] = {"scope": "subset", "rowIds": row_ids}
+    if args.unprocessed_only:
+        payload["unprocessedOnly"] = True
+
+    context = {
+        "mode": "run-next",
+        "selection": {k: v for k, v in selection.items() if k != "row_ids"},
+        "row_ids": row_ids,
+    }
+    _execute_run_flow(args=args, token=token, payload=payload, context=context)
 
 
 def cmd_columns_estimate(args: argparse.Namespace) -> None:
@@ -2272,6 +2499,25 @@ def build_parser() -> argparse.ArgumentParser:
     _add_api_common_arguments(pcr)
     pcr.set_defaults(func=cmd_columns_run)
 
+    pcrn = col_sub.add_parser("run-next", help="Run exactly N selected rows using subset scope")
+    pcrn.add_argument("--table-id", required=True)
+    pcrn.add_argument("--column-id", required=True)
+    pcrn.add_argument("--count", type=int, required=True, help="Exact number of rows to queue")
+    pcrn.add_argument("--filters-json", help="Optional JSON object to select from filtered rows")
+    pcrn.add_argument("--filters-file", help="Optional JSON file to select from filtered rows")
+    pcrn.add_argument("--page-size", type=int, default=200, help="Rows page size while selecting candidates (max 1000)")
+    pcrn.add_argument(
+        "--include-processed",
+        dest="unprocessed_only",
+        action="store_false",
+        help="Include rows that already have output in candidate selection",
+    )
+    pcrn.add_argument("--fail-if-empty", action="store_true", help="Exit non-zero when no eligible rows are selected")
+    pcrn.set_defaults(unprocessed_only=True)
+    _add_run_execution_arguments(pcrn)
+    _add_api_common_arguments(pcrn)
+    pcrn.set_defaults(func=cmd_columns_run_next)
+
     pce = col_sub.add_parser("estimate", help="Estimate a column run")
     pce.add_argument("--table-id", required=True)
     pce.add_argument("--column-id", required=True)
@@ -2340,6 +2586,25 @@ def build_parser() -> argparse.ArgumentParser:
     _add_api_common_arguments(palias_run)
     palias_run.set_defaults(func=cmd_columns_run)
 
+    palias_run_next = sub.add_parser("run-next", help="Alias for: columns run-next")
+    palias_run_next.add_argument("--table-id", required=True)
+    palias_run_next.add_argument("--column-id", required=True)
+    palias_run_next.add_argument("--count", type=int, required=True, help="Exact number of rows to queue")
+    palias_run_next.add_argument("--filters-json", help="Optional JSON object to select from filtered rows")
+    palias_run_next.add_argument("--filters-file", help="Optional JSON file to select from filtered rows")
+    palias_run_next.add_argument("--page-size", type=int, default=200, help="Rows page size while selecting candidates (max 1000)")
+    palias_run_next.add_argument(
+        "--include-processed",
+        dest="unprocessed_only",
+        action="store_false",
+        help="Include rows that already have output in candidate selection",
+    )
+    palias_run_next.add_argument("--fail-if-empty", action="store_true", help="Exit non-zero when no eligible rows are selected")
+    palias_run_next.set_defaults(unprocessed_only=True)
+    _add_run_execution_arguments(palias_run_next)
+    _add_api_common_arguments(palias_run_next)
+    palias_run_next.set_defaults(func=cmd_columns_run_next)
+
     # status
     ps = sub.add_parser("status", help="Show pending/done/error counts for a table/column (Mongo)")
     ps.add_argument("--table-id", required=True)