deepvista-cli 0.4.0__tar.gz → 0.5.0__tar.gz

deepvista_cli-0.5.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.5.0"
+}

{deepvista_cli-0.4.0 → deepvista_cli-0.5.0}/CHANGELOG.md

@@ -37,6 +37,13 @@ users what's new between the version they have installed and the latest release.
   adopts a pre-existing server-side row instead of failing when the local
   file is missing.
 
+## [0.5.0](https://github.com/DeepVista-AI/deepvista-cli/compare/v0.4.0...v0.5.0) (2026-06-04)
+
+
+### Features
+
+* **DV-936:** task_queue run/list/setup commands ([#155](https://github.com/DeepVista-AI/deepvista-cli/issues/155)) ([0d90691](https://github.com/DeepVista-AI/deepvista-cli/commit/0d9069106d14068d657e16415be80dec95f12085))
+
 ## [0.4.0](https://github.com/DeepVista-AI/deepvista-cli/compare/v0.3.0...v0.4.0) (2026-06-03)
 
 

{deepvista_cli-0.4.0 → deepvista_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepvista-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: CLI for DeepVista — chat, notes, skills, and memory from your terminal.
 Project-URL: Homepage, https://deepvista.ai
 Project-URL: Repository, https://github.com/DeepVista-AI/deepvista-cli

{deepvista_cli-0.4.0 → deepvista_cli-0.5.0}/deepvista_cli/commands/skill.py

@@ -133,9 +133,37 @@ def skill_get(ctx: click.Context, skill_id: str) -> None:
         "tool_plan."
     ),
 )
+@click.option(
+    "--webhook",
+    is_flag=True,
+    default=False,
+    help=(
+        "Mark this as a webhook-queued run (DV-955). Appends the task-queue "
+        "completion contract so the host agent reports the queue task after "
+        "`skill complete`. Set automatically on commands the webhook enqueues."
+    ),
+)
+@click.option(
+    "--best-effort",
+    is_flag=True,
+    default=False,
+    help=(
+        "Unattended run: instruct the host agent to answer open questions "
+        "from the vistabase instead of stalling, note assumptions, and only "
+        "pause on hard blockers (DV-955)."
+    ),
+)
 @click.option("--dry-run", is_flag=True, default=False, help="Preview what would happen without making any changes.")
 @click.pass_context
-def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: str, dry_run: bool) -> None:
+def skill_run(
+    ctx: click.Context,
+    skill_id: str,
+    user_input: str | None,
+    mode: str,
+    webhook: bool,
+    best_effort: bool,
+    dry_run: bool,
+) -> None:
     """Run a Skill — host mode by default; ``--mode deepvista`` delegates the whole run server-side.
 
     > [!CAUTION] This is a write command — host mode acquires the parent
@@ -160,6 +188,36 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
         _skill_run_deepvista(ctx, skill_id, user_input, dry_run=dry_run)
         return
 
+    emit_host_run_packet(
+        ctx,
+        skill_id,
+        user_input,
+        mode,
+        dry_run=dry_run,
+        webhook=webhook,
+        best_effort=best_effort,
+    )
+
+
+def emit_host_run_packet(
+    ctx: click.Context,
+    skill_id: str,
+    user_input: str | None,
+    mode: str = "host",
+    *,
+    dry_run: bool = False,
+    webhook: bool = False,
+    best_effort: bool = False,
+    task_id: str | None = None,
+) -> None:
+    """Fetch the skill, acquire the run lock, and print the host run packet.
+
+    Shared by ``skill run`` (host / auto modes) and ``task_queue run --host``
+    (DV-955), which emits packets for webhook-queued workflow tasks instead
+    of subprocess-executing them — a queued workflow needs the surrounding
+    host agent to drive it. ``task_id`` (only known on the task-queue path)
+    threads the queue entry into the completion contract.
+    """
     # host / auto: fetch the card, optionally acquire the lock, and emit a
     # run packet the host agent drives.
     card = _client(ctx).post("/get_context_card", {"card_id": skill_id, "card_type": "skill"})
@@ -196,7 +254,11 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
         "phase_routes": phase_routes,
         "user_input": user_input or "",
         "skill_status": card.get("status", ""),
+        "webhook": webhook,
+        "best_effort": best_effort,
     }
+    if task_id:
+        run_header["task_id"] = task_id
 
     if dry_run:
         format_output(
@@ -222,6 +284,12 @@ def skill_run(ctx: click.Context, skill_id: str, user_input: str | None, mode: s
     click.echo("---")
     click.echo()
     click.echo(_load_host_runtime_contract())
+    if best_effort:
+        click.echo()
+        click.echo(_BEST_EFFORT_STANZA)
+    if webhook:
+        click.echo()
+        click.echo(_webhook_task_stanza(task_id))
 
 
 def _skill_run_deepvista(
@@ -258,6 +326,45 @@ def _load_host_runtime_contract() -> str:
     return resources.files("deepvista_cli.resources").joinpath("workflow_host_runtime.md").read_text(encoding="utf-8")
 
 
+# Appended to the runtime contract for unattended runs (DV-955). The run was
+# triggered by a webhook — there is no human in the loop to answer questions.
+_BEST_EFFORT_STANZA = """\
+## Best-effort mode (unattended run)
+
+This run was triggered without a human in the loop. Do NOT stall waiting
+for answers:
+
+- When a step needs information, search the vistabase first:
+  `deepvista card +search "…"`, `deepvista vistabase +search "…"`,
+  `deepvista notes list`. Prefer an answer found there over asking.
+- When nothing answers, make the most reasonable assumption, state it in
+  the phase's artifact note, and move to the next step.
+- Reserve `deepvista skill phase pause` for hard blockers only (missing
+  credentials, unavailable tools) — never for open questions.
+- Anything that would normally be sent externally (emails, invites) must
+  be left as a DRAFT for human review, never dispatched."""
+
+
+def _webhook_task_stanza(task_id: str | None) -> str:
+    """Completion contract for webhook-queued runs (DV-955).
+
+    The queue entry stays ``running`` until the host agent reports it —
+    nothing else will, so skipping this leaves a permanently stuck task.
+    """
+    task_ref = task_id or "<task_id from `deepvista task_queue list`>"
+    return f"""\
+## Webhook task completion
+
+This run came off the agent task queue. The queue entry stays `running`
+until YOU report it — after `deepvista skill complete` (or on failure):
+
+```
+deepvista task_queue complete {task_ref} --status completed
+# or, when the run could not finish:
+deepvista task_queue complete {task_ref} --status failed --note "<one short sentence>"
+```"""
+
+
 # ---------------------------------------------------------------------------
 # Phase mutators — used by host agents driving the workflow themselves
 # ---------------------------------------------------------------------------

deepvista_cli-0.5.0/deepvista_cli/commands/task_queue.py

@@ -0,0 +1,524 @@
+"""deepvista task_queue — pull-based execution of queued CLI commands (DV-936).
+
+The web app enqueues DeepVista CLI commands onto a managed agent's
+`task_queue`; this command group lets the agent's machine poll and run them:
+
+  deepvista task_queue run      — claim pending tasks and execute them
+  deepvista task_queue list     — show this machine's queue
+  deepvista task_queue complete — report a workflow task's outcome (host agent)
+  deepvista task_queue setup    — install a crontab entry that polls periodically
+
+Workflow tasks (DV-955): webhook-queued `deepvista skill run` entries can't
+be subprocess-executed — a workflow needs the surrounding host agent (Claude
+Code etc.) to drive its phases. `task_queue run --host` claims them and
+emits their run packets to stdout for the host agent; headless runs (cron)
+claim command-only so workflow tasks stay pending until a host run. The
+host agent reports the outcome via `task_queue complete` after
+`skill complete`.
+
+Safety: only commands whose first token is `deepvista` are executed
+(shlex-parsed, shell=False). The backend enforces the same allowlist at
+enqueue time; the check here guards against tampered queue rows.
+"""
+
+from __future__ import annotations
+
+import json as _json
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+from deepvista_cli.client.http import DeepVistaClient
+from deepvista_cli.client.origin import detect_agent_tool
+from deepvista_cli.commands.agents import AGENTS_DIR, _load_agent_id
+from deepvista_cli.commands.skill import emit_host_run_packet
+from deepvista_cli.config import CONFIG_DIR
+from deepvista_cli.output.formatter import format_output, output_error
+
+TASK_COLUMNS = ["id", "status", "command", "created_at", "finished_at", "exit_code"]
+
+# Only the DeepVista CLI itself may be invoked from the queue.
+ALLOWED_COMMAND_BINARY = "deepvista"
+
+# Per-task execution budget; a hung task must not wedge the cron tick forever.
+TASK_TIMEOUT_SECONDS = 600
+
+# Reported output is truncated to a tail (mirrors the backend cap).
+OUTPUT_TAIL_MAX_CHARS = 2000
+
+# Marker comment identifying crontab entries owned by `task_queue setup`.
+CRON_MARKER = "# deepvista-task-queue"
+
+CRON_LOG_PATH = CONFIG_DIR / "task_queue.log"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _client(ctx: click.Context) -> DeepVistaClient:
+    return ctx.obj._client
+
+
+def _output(ctx: click.Context, data: object, **kwargs: object) -> None:
+    format_output(data, ctx.obj.output_format, **kwargs)  # type: ignore[arg-type]
+
+
+def _resolve_machine_agent_id(agent_type: str | None, agent_role: str | None) -> str | None:
+    """Find the registered agent this machine's queue belongs to.
+
+    Resolution order: explicit --type/--role, then the detected host tool,
+    then the most recently registered agent of any type on this machine.
+    """
+    if agent_type:
+        return _load_agent_id(agent_type, agent_role)
+
+    try:
+        detected, _ = detect_agent_tool()
+    except Exception:
+        detected = None
+    if detected:
+        agent_id = _load_agent_id(detected, agent_role)
+        if agent_id:
+            return agent_id
+
+    # Cron runs outside any agent host — fall back to the newest registration.
+    candidates: list[tuple[float, Path]] = []
+    if AGENTS_DIR.exists():
+        for path in AGENTS_DIR.glob("*.json"):
+            try:
+                candidates.append((path.stat().st_mtime, path))
+            except OSError:
+                continue
+    candidates.sort(reverse=True)
+    for _, path in candidates:
+        try:
+            agent_id = _json.loads(path.read_text()).get("agent_id")
+        except (OSError, _json.JSONDecodeError):
+            continue
+        if agent_id:
+            return agent_id
+    return None
+
+
+def _require_machine_agent_id(agent_type: str | None, agent_role: str | None) -> str:
+    agent_id = _resolve_machine_agent_id(agent_type, agent_role)
+    if not agent_id:
+        output_error(3, "No registered agent on this machine", "Run 'deepvista agents register' first.")
+        raise SystemExit(3)
+    return agent_id
+
+
+def _deepvista_binary() -> str:
+    """Absolute path to the `deepvista` entry point (cron has a minimal PATH)."""
+    binary = shutil.which(ALLOWED_COMMAND_BINARY)
+    if binary:
+        return binary
+    if sys.argv and Path(sys.argv[0]).name == ALLOWED_COMMAND_BINARY:
+        return str(Path(sys.argv[0]).resolve())
+    return ALLOWED_COMMAND_BINARY
+
+
+def _validate_command(command: str) -> str | None:
+    """Return an error message when `command` is not an allowed CLI invocation."""
+    try:
+        tokens = shlex.split(command)
+    except ValueError as exc:
+        return f"Command is not shell-parseable: {exc}"
+    if not tokens:
+        return "Command is empty"
+    if tokens[0] != ALLOWED_COMMAND_BINARY:
+        return f"Only '{ALLOWED_COMMAND_BINARY}' commands can run from the task queue"
+    return None
+
+
+def _is_workflow_task(task: dict) -> bool:
+    """True when the task is a webhook-queued workflow run (DV-955).
+
+    Primary signal is the advisory ``source: "webhook"`` key the backend
+    stamps at enqueue time; the command-shape fallback covers queues
+    written before that key existed.
+    """
+    if task.get("source") == "webhook":
+        return True
+    try:
+        tokens = shlex.split(str(task.get("command", "")))
+    except ValueError:
+        return False
+    return tokens[:3] == [ALLOWED_COMMAND_BINARY, "skill", "run"] and "--webhook" in tokens
+
+
+def _parse_workflow_command(command: str) -> dict | None:
+    """Extract skill_id / --input / --best-effort from a queued skill-run command.
+
+    The webhook composes these commands with a fixed shape
+    (``deepvista skill run --mode host <id> --input <json> --webhook
+    [--best-effort]``); parse defensively anyway since queue rows are data.
+    Returns None when the command isn't a recognizable skill run.
+    """
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return None
+    if tokens[:3] != [ALLOWED_COMMAND_BINARY, "skill", "run"]:
+        return None
+
+    value_opts = {"--mode", "--input"}
+    values: dict[str, str] = {}
+    skill_id: str | None = None
+    i = 3
+    while i < len(tokens):
+        token = tokens[i]
+        if token in value_opts:
+            if i + 1 < len(tokens):
+                values[token] = tokens[i + 1]
+            i += 2
+        elif token.startswith("--"):
+            i += 1
+        elif skill_id is None:
+            skill_id = token
+            i += 1
+        else:
+            i += 1
+
+    if not skill_id:
+        return None
+    return {
+        "skill_id": skill_id,
+        "user_input": values.get("--input"),
+        "best_effort": "--best-effort" in tokens,
+    }
+
+
+def _emit_workflow_task(ctx: click.Context, agent_id: str, task: dict) -> dict:
+    """Print a claimed workflow task's run packet for the host agent (DV-955).
+
+    The task is left ``running`` on purpose — the host agent drives the
+    workflow and reports the outcome via ``task_queue complete``. Only an
+    unparseable/unloadable task is failed here, since no agent could ever
+    pick it up.
+    """
+    task_id = str(task.get("id", ""))
+    command = str(task.get("command", ""))
+
+    parsed = _parse_workflow_command(command)
+    if parsed is None:
+        _client(ctx).post(
+            f"/agents/{agent_id}/task-queue/{task_id}/result",
+            {"status": "failed", "exit_code": None, "output_tail": "Unparseable workflow task command"},
+        )
+        return {"task_id": task_id, "command": command, "status": "failed", "exit_code": None}
+
+    click.echo()
+    click.echo(f"=== DEEPVISTA WORKFLOW TASK {task_id} (skill {parsed['skill_id']}) ===")
+    click.echo()
+    try:
+        emit_host_run_packet(
+            ctx,
+            parsed["skill_id"],
+            parsed["user_input"],
+            "host",
+            webhook=True,
+            best_effort=parsed["best_effort"],
+            task_id=task_id,
+        )
+    except SystemExit:
+        # Skill gone / empty / phaseless — no host agent can ever run this
+        # task, so fail it instead of leaving it stuck in `running`.
+        _client(ctx).post(
+            f"/agents/{agent_id}/task-queue/{task_id}/result",
+            {"status": "failed", "exit_code": None, "output_tail": "Skill not found or not runnable"},
+        )
+        return {"task_id": task_id, "command": command, "status": "failed", "exit_code": None}
+    return {"task_id": task_id, "command": command, "status": "running", "exit_code": None}
+
+
+def _execute_task(ctx: click.Context, agent_id: str, task: dict) -> dict:
+    """Run one claimed task and report its terminal result to the backend."""
+    task_id = str(task.get("id", ""))
+    command = str(task.get("command", ""))
+
+    validation_error = _validate_command(command)
+    if validation_error:
+        status, exit_code, output_tail = "failed", None, validation_error
+    else:
+        argv = shlex.split(command)
+        argv[0] = _deepvista_binary()
+        try:
+            proc = subprocess.run(  # noqa: S603 — argv is allowlist-validated, shell=False
+                argv,
+                capture_output=True,
+                text=True,
+                timeout=TASK_TIMEOUT_SECONDS,
+            )
+            exit_code = proc.returncode
+            status = "completed" if exit_code == 0 else "failed"
+            output_tail = ((proc.stdout or "") + (proc.stderr or ""))[-OUTPUT_TAIL_MAX_CHARS:]
+        except subprocess.TimeoutExpired:
+            status, exit_code, output_tail = "failed", None, f"Timed out after {TASK_TIMEOUT_SECONDS}s"
+        except OSError as exc:
+            status, exit_code, output_tail = "failed", None, str(exc)
+
+    _client(ctx).post(
+        f"/agents/{agent_id}/task-queue/{task_id}/result",
+        {"status": status, "exit_code": exit_code, "output_tail": output_tail},
+    )
+    return {"task_id": task_id, "command": command, "status": status, "exit_code": exit_code}
+
+
+# ---------------------------------------------------------------------------
+# Command group
+# ---------------------------------------------------------------------------
+
+
+@click.group("task_queue")
+def task_queue_group() -> None:
+    """Run CLI commands queued for this machine's agent."""
+
+
+def _detect_host_agent() -> bool:
+    """True when an AI agent host (Claude Code, OpenClaw, …) drives this CLI."""
+    try:
+        detected, _ = detect_agent_tool()
+    except Exception:
+        return False
+    return bool(detected) and detected != "deepvista-cli"
+
+
+@task_queue_group.command("run")
+@click.option("--type", "agent_type", default=None, help="Resolve agent by type from local storage.")
+@click.option("--role", "agent_role", default=None, help="Resolve agent by role (with --type).")
+@click.option(
+    "--host",
+    "host_mode",
+    is_flag=True,
+    default=False,
+    help=(
+        "Claim workflow tasks too and emit their run packets for the host "
+        "agent to drive (DV-955). Auto-enabled when an agent host is "
+        "detected; headless runs claim command tasks only."
+    ),
+)
+@click.pass_context
+def task_queue_run(ctx: click.Context, agent_type: str | None, agent_role: str | None, host_mode: bool) -> None:
+    """Claim pending tasks for this machine's agent and execute them.
+
+    Returns immediately when the queue is empty, so it's cheap as a cron
+    tick. Plain command tasks run sequentially via subprocess and their
+    results are reported back. Workflow tasks (webhook-queued skill runs)
+    are only claimed in host mode: their run packets are printed for the
+    surrounding agent to drive, and the entries stay ``running`` until the
+    agent calls ``task_queue complete``.
+    """
+    agent_id = _require_machine_agent_id(agent_type, agent_role)
+    host_mode = host_mode or _detect_host_agent()
+
+    data = _client(ctx).post(
+        f"/agents/{agent_id}/task-queue/claim",
+        None if host_mode else {"command_only": True},
+    )
+    if not data.get("success"):
+        output_error(1, "Failed to claim tasks", data.get("error", "Unknown error"))
+        raise SystemExit(1)
+
+    tasks = data.get("tasks") or []
+    if not tasks:
+        _output(ctx, {"agent_id": agent_id, "tasks_run": 0}, title="Task Queue")
+        return
+
+    command_tasks = [t for t in tasks if not _is_workflow_task(t)]
+    # Workflow tasks only reach this list in host mode (headless claims are
+    # command_only) — the guard below covers a backend that predates the
+    # filter, so a cron tick never swallows a packet nobody will read.
+    workflow_tasks = [t for t in tasks if _is_workflow_task(t)] if host_mode else []
+
+    results = [_execute_task(ctx, agent_id, task) for task in command_tasks]
+    failed = sum(1 for r in results if r["status"] == "failed")
+    _output(
+        ctx,
+        {
+            "agent_id": agent_id,
+            "tasks_run": len(results),
+            "failed": failed,
+            "results": results,
+            "workflow_tasks": len(workflow_tasks),
+        },
+        title="Task Queue",
+    )
+
+    # Workflow packets go last so the runtime contract (and its completion
+    # instructions) is the freshest thing in the host agent's context.
+    for task in workflow_tasks:
+        _emit_workflow_task(ctx, agent_id, task)
+
+
+@task_queue_group.command("list")
+@click.option("--type", "agent_type", default=None, help="Resolve agent by type from local storage.")
+@click.option("--role", "agent_role", default=None, help="Resolve agent by role (with --type).")
+@click.pass_context
+def task_queue_list(ctx: click.Context, agent_type: str | None, agent_role: str | None) -> None:
+    """Show the task queue for this machine's agent.
+
+    Read-only.
+    """
+    agent_id = _require_machine_agent_id(agent_type, agent_role)
+    data = _client(ctx).get(f"/agents/{agent_id}/task-queue")
+    if data.get("error"):
+        output_error(1, "Failed to list tasks", data["error"])
+        raise SystemExit(1)
+    tasks = data.get("tasks", [])
+    _output(
+        ctx,
+        {"agent_id": agent_id, "tasks": tasks, "count": len(tasks)},
+        columns=TASK_COLUMNS,
+        title="Task Queue",
+    )
+
+
+@task_queue_group.command("complete")
+@click.argument("task_id")
+@click.option(
+    "--status",
+    type=click.Choice(["completed", "failed"]),
+    required=True,
+    help="Terminal outcome of the workflow task.",
+)
+@click.option("--note", default=None, help="Short outcome note stored as the task's output tail.")
+@click.option("--type", "agent_type", default=None, help="Resolve agent by type from local storage.")
+@click.option("--role", "agent_role", default=None, help="Resolve agent by role (with --type).")
+@click.pass_context
+def task_queue_complete(
+    ctx: click.Context,
+    task_id: str,
+    status: str,
+    note: str | None,
+    agent_type: str | None,
+    agent_role: str | None,
+) -> None:
+    """Report the terminal outcome of a claimed workflow task (DV-955).
+
+    Called by the host agent after driving a webhook-queued workflow run to
+    its end (`deepvista skill complete`) — or to its failure. Plain command
+    tasks report automatically; this is only needed for workflow tasks,
+    which stay ``running`` until someone reports them.
+    """
+    agent_id = _require_machine_agent_id(agent_type, agent_role)
+    data = _client(ctx).post(
+        f"/agents/{agent_id}/task-queue/{task_id}/result",
+        {"status": status, "exit_code": 0 if status == "completed" else 1, "output_tail": note},
+    )
+    if not data.get("success"):
+        output_error(1, "Failed to report task result", data.get("error", "Unknown error"))
+        raise SystemExit(1)
+    _output(ctx, {"agent_id": agent_id, "task": data.get("task")}, title="Task Queue")
+
+
+# ---------------------------------------------------------------------------
+# Cron setup
+# ---------------------------------------------------------------------------
+
+
+def _read_crontab() -> list[str]:
+    """Current user crontab lines ([] when none exists)."""
+    try:
+        proc = subprocess.run(  # noqa: S603
+            ["crontab", "-l"],  # noqa: S607
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return []
+    if proc.returncode != 0:
+        return []
+    return proc.stdout.splitlines()
+
+
+def _write_crontab(lines: list[str]) -> bool:
+    content = "\n".join(lines) + ("\n" if lines else "")
+    try:
+        proc = subprocess.run(  # noqa: S603
+            ["crontab", "-"],  # noqa: S607
+            input=content,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return proc.returncode == 0
+
+
+def _cron_entry(interval: int, profile: str) -> str:
+    binary = _deepvista_binary()
+    profile_flag = f" --profile {profile}" if profile and profile != "default" else ""
+    return f"*/{interval} * * * * {binary}{profile_flag} task_queue run >> {CRON_LOG_PATH} 2>&1 {CRON_MARKER}"
+
+
+@task_queue_group.command("setup")
+@click.option(
+    "--interval",
+    default=5,
+    show_default=True,
+    type=click.IntRange(1, 1440),
+    help="Poll interval in minutes.",
+)
+@click.option("--remove", is_flag=True, default=False, help="Uninstall the cron entry instead.")
+@click.pass_context
+def task_queue_setup(ctx: click.Context, interval: int, remove: bool) -> None:
+    """Install a crontab entry that runs `deepvista task_queue run` periodically.
+
+    Idempotent — re-running replaces any existing entry. Use --remove to
+    uninstall. Crontab only (macOS/Linux); on Windows, schedule
+    `deepvista task_queue run` with Task Scheduler instead.
+
+    Cron runs are headless: they execute plain command tasks only and
+    leave workflow tasks (webhook-queued skill runs) pending. Drive those
+    from an agent session with `deepvista task_queue run --host`.
+
+    > [!CAUTION] This is a write command — confirm with the user before executing.
+    """
+    if sys.platform == "win32":
+        output_error(1, "Unsupported platform", "Crontab setup is macOS/Linux only.")
+        raise SystemExit(1)
+
+    existing = _read_crontab()
+    kept = [line for line in existing if CRON_MARKER not in line]
+    entry = None if remove else _cron_entry(interval, getattr(ctx.obj, "profile", "default"))
+    updated = kept + ([entry] if entry else [])
+
+    if ctx.obj.dry_run:
+        _output(
+            ctx,
+            {
+                "dry_run": True,
+                "would": "remove cron entry" if remove else "install cron entry",
+                "entry": entry,
+                "removed_entries": [line for line in existing if CRON_MARKER in line],
+            },
+            title="Dry Run: Task Queue Setup",
+        )
+        return
+
+    if remove and len(kept) == len(existing):
+        _output(ctx, {"removed": False, "message": "No task-queue cron entry installed."}, title="Task Queue Setup")
+        return
+
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    if not _write_crontab(updated):
+        output_error(1, "Failed to update crontab", "Is `crontab` available on this machine?")
+        raise SystemExit(1)
+
+    if remove:
+        _output(ctx, {"removed": True}, title="Task Queue Setup")
+    else:
+        _output(
+            ctx,
+            {"installed": True, "interval_minutes": interval, "entry": entry, "log": str(CRON_LOG_PATH)},
+            title="Task Queue Setup",
+        )