agentwire-dev 1.22.0__tar.gz → 1.23.0__tar.gz

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/CHANGELOG.md

@@ -7,8 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.23.0] - 2026-04-16
+
 ### Added
 
+- **Workflow-backed scheduler tasks** — scheduler can now dispatch a pi workflow DAG in-process instead of shelling out to `agentwire ensure` (Phase 3 of the pi workflow roadmap)
+  - New `workflow:` + `inputs:` fields on scheduler tasks in `~/.agentwire/scheduler.yaml` (mutually exclusive with `task:`)
+  - `dispatch_task()` routes automatically: ensure path unchanged, new `_dispatch_workflow_task` calls `run_workflow()` in-process — no tmux, no Claude Code subprocess
+  - Status mapping: workflow `success→complete`, `partial→incomplete`, `failure→failed`
+  - Scheduler `{{ task }}`, `{{ project }}`, `{{ session }}`, `{{ workflow }}` variables expand in string `inputs:` values
+  - `agentwire scheduler run <name> --dry-run` prints the workflow plan without touching state
+  - `task_completed` events now carry `workflow`, `run_id`, and per-node `nodes[]` when the task is workflow-backed
+  - Morning report (`agentwire scheduler report --artifact`) renders per-node status badges + run-id breadcrumb for workflow rows
+  - `agentwire scheduler history --json` includes the `workflow` name per task
+  - Full reference: `docs/workflows.md` → "Scheduler integration"; compare/contrast: `docs/scheduled-workloads.md`
 - **Kokoro TTS engine** — CPU-only ultra-lightweight backend (`kokoro`)
   - Kokoro 82M ONNX model via `kokoro-onnx`, auto-downloads ~170 MB from HuggingFace on first use
   - No GPU required — pure ONNX CPU inference, near real-time on Apple Silicon / modern Intel CPU
@@ -16,6 +28,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Streaming support via `create_stream()`
   - Runs in dedicated `.venv-kokoro` with CPU-only PyTorch (~250 MB vs 2 GB+ CUDA builds)
 
+### Fixed
+
+- `cmd_scheduler_report` was calling `read_events(limit=500)` with the wrong kwarg name; the `except` silently caught the `TypeError` so morning reports quietly returned 0 events. Now calls `read_events(tail=500)`.
+
 ## [1.9.0] - 2026-03-13
 
 ### Added

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentwire-dev
-Version: 1.22.0
+Version: 1.23.0
 Summary: Multi-session voice web interface for AI coding agents
 Project-URL: Homepage, https://agentwire.dev
 Project-URL: Repository, https://github.com/dotdevdotdev/agentwire-dev

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/agentwire/__init__.py

@@ -1,3 +1,3 @@
 """AgentWire - Multi-session voice web interface for AI coding agents."""
 
-__version__ = "1.22.0"
+__version__ = "1.23.0"

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/agentwire/__main__.py

@@ -8744,9 +8744,10 @@ def cmd_scheduler_board(args) -> int:
 
 def cmd_scheduler_run(args) -> int:
     """Force-run a specific task now."""
-    from .scheduler import dispatch_task, load_board, save_board
+    from .scheduler import _render_workflow_inputs, dispatch_task, load_board, save_board
 
     json_mode = getattr(args, 'json', False)
+    dry_run = getattr(args, 'dry_run', False)
     name = args.name
 
     try:
@@ -8760,6 +8761,40 @@ def cmd_scheduler_run(args) -> int:
             f"Task '{name}' not found in board. Available: {', '.join(board.tasks.keys())}",
         )
 
+    task = board.tasks[name]
+
+    if dry_run:
+        if not task.workflow:
+            return _output_result(
+                False, json_mode,
+                f"--dry-run only applies to workflow tasks; '{name}' runs via ensure.",
+            )
+        from agentwire.workflows.definitions import resolve_workflow
+        from agentwire.workflows.runner import run_workflow
+        try:
+            wf = resolve_workflow(task.workflow)
+        except Exception as e:
+            return _output_result(False, json_mode, f"Could not load workflow '{task.workflow}': {e}")
+        rendered_inputs = _render_workflow_inputs(task.inputs, task)
+        run = run_workflow(wf, runs_dir=None, inputs=rendered_inputs, dry_run=True)
+        if json_mode:
+            _output_json({
+                "success": True,
+                "task": name,
+                "dry_run": True,
+                "workflow": wf.name,
+                "inputs": rendered_inputs,
+                "nodes": [r.node_id for r in run.node_results],
+                "status": run.status,
+            })
+            return 0
+        print(f"Dry-run: {name} → workflow '{wf.name}'")
+        if rendered_inputs:
+            print(f"  inputs: {rendered_inputs}")
+        for r in run.node_results:
+            print(f"  - {r.node_id}: {r.final_text}")
+        return 0
+
     if not json_mode:
         print(f"Running: {name}")
 
@@ -8835,12 +8870,14 @@ def cmd_scheduler_history(args) -> int:
     if json_mode:
         history = []
         for name, state in board.state.items():
+            task = board.tasks.get(name)
             history.append({
                 "task": name,
                 "last_run": state.last_run.isoformat() if state.last_run else None,
                 "last_status": state.last_status,
                 "last_duration": state.last_duration,
                 "run_count": state.run_count,
+                "workflow": (task.workflow if task else "") or None,
             })
         _output_json({"success": True, "history": history})
         return 0
@@ -8867,6 +8904,7 @@ def cmd_scheduler_history(args) -> int:
 def cmd_scheduler_report(args) -> int:
     """Generate a morning report HTML artifact of recent task runs."""
     import re as _re
+    from html import escape as html_escape
     from .scheduler import _parse_duration, format_interval, load_board, read_events
 
     json_mode = getattr(args, 'json', False)
@@ -8886,7 +8924,7 @@ def cmd_scheduler_report(args) -> int:
 
     # Load events in the window
     try:
-        events = read_events(limit=500)
+        events = read_events(tail=500)
     except Exception:
         events = []
 
@@ -8912,6 +8950,9 @@ def cmd_scheduler_report(args) -> int:
             "timestamp": ts.strftime("%Y-%m-%d %H:%M"),
             "work_branch": "",
             "pr_url": "",
+            "workflow": ev.get("workflow", ""),
+            "run_id": ev.get("run_id", ""),
+            "nodes": ev.get("nodes") or [],
         }
         runs.append(run)
 
@@ -8935,20 +8976,48 @@ def cmd_scheduler_report(args) -> int:
         color = colors.get(status, "#78909c")
         return f'<span style="background:{color};color:#fff;padding:2px 8px;border-radius:12px;font-size:0.85em">{status}</span>'
 
+    def node_badges(nodes: list) -> str:
+        if not nodes:
+            return ""
+        node_colors = {
+            "success": "#00c853",
+            "failure": "#ff5252",
+            "timeout": "#ff7043",
+            "skipped": "#78909c",
+        }
+        pieces = []
+        for n in nodes:
+            nid = html_escape(str(n.get("id", "?")))
+            nstatus = str(n.get("status", "?"))
+            color = node_colors.get(nstatus, "#556")
+            pieces.append(
+                f'<span style="background:{color};color:#fff;padding:1px 6px;border-radius:8px;font-size:0.75em;margin-right:3px">{nid}</span>'
+            )
+        return "".join(pieces)
+
     rows_html = ""
     for r in runs:
         duration_str = format_interval(r["duration"]) if r["duration"] else "-"
         pr_link = f'<a href="{r["pr_url"]}" target="_blank" style="color:#00d4ff">{r["pr_url"][:40]}...</a>' if r.get("pr_url") else "-"
-        branch_str = r.get("work_branch") or "-"
+        branch_col = ""
+        if r.get("workflow"):
+            wf_label = html_escape(r["workflow"])
+            run_id = html_escape(r.get("run_id", ""))
+            badges = node_badges(r["nodes"])
+            run_hint = f' <span style="color:#556;font-size:0.75em">({run_id[:20]}…)</span>' if run_id else ""
+            branch_col = f'<code style="font-size:0.85em">workflow:{wf_label}</code>{run_hint}<div style="margin-top:4px">{badges}</div>'
+        else:
+            branch_col = f'<code style="font-size:0.85em">{r.get("work_branch") or "-"}</code>'
+        summary_text = r["summary"][:120] if r["summary"] else "-"
         rows_html += f"""
         <tr>
           <td style="font-weight:600">{r["task"]}</td>
           <td>{status_badge(r["status"])}</td>
           <td>{r["timestamp"]}</td>
           <td>{duration_str}</td>
-          <td><code style="font-size:0.85em">{branch_str}</code></td>
+          <td>{branch_col}</td>
           <td>{pr_link}</td>
-          <td style="color:#aaa;font-size:0.85em">{r["summary"][:120] if r["summary"] else "-"}</td>
+          <td style="color:#aaa;font-size:0.85em">{summary_text}</td>
         </tr>"""
 
     if not rows_html:
@@ -10550,7 +10619,12 @@ def main() -> int:
     scheduler_parser = subparsers.add_parser(
         "scheduler",
         help="Manage the task scheduler",
-        description="Centralized daemon that dispatches tasks across projects on a shared cadence.",
+        description=(
+            "Centralized daemon that dispatches tasks across projects on a shared cadence. "
+            "Tasks in ~/.agentwire/scheduler.yaml are either ensure tasks (task: + session:) "
+            "or workflow tasks (workflow: + inputs:) — the scheduler routes each automatically. "
+            "See docs/scheduled-workloads.md."
+        ),
     )
     scheduler_subparsers = scheduler_parser.add_subparsers(dest="scheduler_command")
 
@@ -10580,6 +10654,8 @@ def main() -> int:
     sched_run = scheduler_subparsers.add_parser("run", help="Force-run a task now")
     sched_run.add_argument("name", help="Task name from board")
     sched_run.add_argument("--json", action="store_true", help="Output JSON")
+    sched_run.add_argument("--dry-run", action="store_true",
+                           help="For workflow tasks: print the execution plan without running")
     sched_run.set_defaults(func=cmd_scheduler_run)
 
     # scheduler enable <name>

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/agentwire/scheduler.py

@@ -74,16 +74,18 @@ class Schedule:
 @dataclass
 class SchedulerTask:
     name: str
-    project: str          # ~/projects/foo (expanded at load time)
-    session: str          # session name for ensure
-    task: str             # task name in project's .agentwire.yml
-    schedule: Schedule    # REQUIRED (replaces interval)
+    project: str = ""     # ~/projects/foo (expanded at load time) — optional for workflow tasks
+    session: str = ""     # session name for ensure (required iff task is set)
+    task: str = ""        # task name in project's .agentwire.yml (mutually exclusive with workflow)
+    workflow: str = ""    # workflow name or YAML path (mutually exclusive with task)
+    inputs: dict = field(default_factory=dict)  # workflow inputs passed to run_workflow
+    schedule: Schedule = field(default_factory=Schedule)  # REQUIRED (replaces interval)
     enabled: bool = True
     filler: bool = False  # only runs in spare cycles
     priority: int = 99    # task ordering (lower = higher priority)
-    type: str | None = None  # session type override (e.g., claude-bypass)
-    roles: list[str] | None = None  # role override (e.g., ["task-runner"])
-    model: str | None = None  # model override (e.g., "haiku")
+    type: str | None = None  # session type override (e.g., claude-bypass) — ignored for workflow tasks
+    roles: list[str] | None = None  # role override — ignored for workflow tasks
+    model: str | None = None  # model override — ignored for workflow tasks
     gate: dict | None = None  # precondition gate (git_commit, git_diff, command)
     max_runs: int | None = None  # auto-disable after N successful dispatches
     once: bool = False           # shorthand for max_runs: 1
@@ -216,11 +218,28 @@ def load_board() -> Board:
 
         schedule = _parse_schedule(t.get("schedule"))
 
+        raw_project = t.get("project", "")
+        project_path = str(Path(raw_project).expanduser()) if raw_project else ""
+
+        workflow = str(t.get("workflow") or "")
+        raw_inputs = t.get("inputs") or {}
+        if not isinstance(raw_inputs, dict):
+            raw_inputs = {}
+
+        if workflow:
+            session_name = str(t.get("session") or "")
+            task_name = str(t.get("task") or "")
+        else:
+            session_name = str(t.get("session") or name)
+            task_name = str(t.get("task") or name)
+
         board.tasks[name] = SchedulerTask(
             name=name,
-            project=str(Path(t.get("project", "")).expanduser()),
-            session=t.get("session", name),
-            task=t.get("task", name),
+            project=project_path,
+            session=session_name,
+            task=task_name,
+            workflow=workflow,
+            inputs=dict(raw_inputs),
             schedule=schedule,
             enabled=bool(t.get("enabled", True)),
             filler=bool(t.get("filler", False)),
@@ -986,7 +1005,7 @@ def _auto_commit(task: SchedulerTask, task_name: str, status: str) -> None:
 
 
 def dispatch_task(board: Board, task_name: str) -> TaskState:
-    """Run a task via `agentwire ensure` and return updated state.
+    """Run a task (workflow DAG or `agentwire ensure`) and return updated state.
 
     Args:
         board: Current board (for reading task config).
@@ -998,16 +1017,8 @@ def dispatch_task(board: Board, task_name: str) -> TaskState:
     task = board.tasks[task_name]
     existing_state = board.state.get(task_name, TaskState())
 
-    # Clear from gated set so gate can be re-evaluated after this run
     _gated_tasks.discard(task_name)
 
-    # Clean stale lock for this session before dispatching.
-    # Stale locks (from crashed ensure processes) cause --skip-if-locked
-    # to silently exit 0, making tasks appear to complete instantly.
-    from .locking import remove_stale_lock
-    remove_stale_lock(task.session)
-
-    # Set last_dispatch BEFORE running for restart safety
     existing_state.last_dispatch = datetime.now(timezone.utc)
     board.state[task_name] = existing_state
     save_board(board)
@@ -1015,6 +1026,21 @@ def dispatch_task(board: Board, task_name: str) -> TaskState:
     _log_event("task_started", task=task_name, session=task.session,
                project=task.project, attempt=existing_state.run_count + 1)
 
+    if task.workflow:
+        return _dispatch_workflow_task(board, task, existing_state)
+    return _dispatch_ensure_task(board, task, existing_state)
+
+
+def _dispatch_ensure_task(board: Board, task: SchedulerTask, existing_state: TaskState) -> TaskState:
+    """Dispatch via `agentwire ensure` subprocess (tmux session path)."""
+    task_name = task.name
+
+    # Clean stale lock for this session before dispatching.
+    # Stale locks (from crashed ensure processes) cause --skip-if-locked
+    # to silently exit 0, making tasks appear to complete instantly.
+    from .locking import remove_stale_lock
+    remove_stale_lock(task.session)
+
     has_overrides = bool(task.type or task.roles is not None or task.model)
 
     if has_overrides:
@@ -1065,31 +1091,232 @@ def dispatch_task(board: Board, task_name: str) -> TaskState:
             run_count=existing_state.run_count,
         )
 
-    # Parse summary from ensure output
     summary, files_modified, blockers_list = _parse_ensure_summary(task, result)
 
-    # Log completion event
     _log_event("task_completed", task=task_name, session=task.session,
                status=status, duration=duration, summary=summary,
                files_modified=files_modified, blockers=blockers_list)
 
-    # Notify portal
     _notify_portal(task_name, status, duration, summary)
 
-    # Auto-commit any changes the task made (each task = one revertable commit)
     _auto_commit(task, task_name, status)
 
-    # Capture HEAD for gate checks on next run
-    gate_commit = ""
+    gate_commit = _capture_head(task.project)
+
+    new_run_count = existing_state.run_count + 1
+    new_state = TaskState(
+        last_run=datetime.now(timezone.utc),
+        last_status=status,
+        last_duration=duration,
+        run_count=new_run_count,
+        last_summary=summary,
+        last_gate_commit=gate_commit,
+    )
+
+    if task.max_runs is not None and new_run_count >= task.max_runs:
+        task.enabled = False
+        board.state[task_name] = new_state
+        save_board(board)
+        _log_event("task_disabled", task=task_name, reason="max_runs_reached",
+                   run_count=new_run_count, max_runs=task.max_runs)
+
+    return new_state
+
+
+def _capture_head(project: str) -> str:
+    """Return the current HEAD SHA of a git repo, or '' if unavailable."""
+    if not project:
+        return ""
     try:
-        head_result = subprocess.run(
-            ["git", "-C", task.project, "rev-parse", "HEAD"],
+        result = subprocess.run(
+            ["git", "-C", project, "rev-parse", "HEAD"],
             capture_output=True, text=True, timeout=_sched_config().git_timeout,
         )
-        if head_result.returncode == 0:
-            gate_commit = head_result.stdout.strip()
+        if result.returncode == 0:
+            return result.stdout.strip()
     except Exception:
         pass
+    return ""
+
+
+# Workflow dispatch ---------------------------------------------------------
+
+_WORKFLOW_STATUS_TO_SCHED = {
+    "success": "complete",
+    "partial": "incomplete",
+    "failure": "failed",
+}
+
+_SCHED_INPUT_VAR_RE = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+def _render_workflow_inputs(inputs: dict, task: SchedulerTask) -> dict:
+    """Expand `{{ task }}`, `{{ project }}`, `{{ session }}`, `{{ workflow }}` in string inputs.
+
+    Unknown variables pass through untouched so workflow nodes can reference their
+    own Jinja variables without collision.
+    """
+    vars_ = {
+        "task": task.name,
+        "project": task.project,
+        "session": task.session,
+        "workflow": task.workflow,
+    }
+
+    def _sub(value):
+        if not isinstance(value, str):
+            return value
+        return _SCHED_INPUT_VAR_RE.sub(
+            lambda m: vars_[m.group(1)] if m.group(1) in vars_ else m.group(0),
+            value,
+        )
+
+    return {k: _sub(v) for k, v in (inputs or {}).items()}
+
+
+def _parse_workflow_summary(run) -> tuple[str, list[str], list[str]]:
+    """Build a single-line summary + rough blockers list from a workflow run."""
+    node_line = ", ".join(f"{r.node_id}={r.status}" for r in run.node_results) or "(no nodes)"
+    head = f"{run.workflow} → {run.status}"
+    last_text = ""
+    for r in reversed(run.node_results):
+        if r.final_text:
+            first_line = r.final_text.strip().splitlines()[0] if r.final_text.strip() else ""
+            last_text = first_line[:200]
+            break
+    summary = f"{head}: {node_line}" + (f" — {last_text}" if last_text else "")
+    blockers: list[str] = []
+    if run.error:
+        blockers.append(run.error)
+    for r in run.node_results:
+        if r.status in ("failure", "timeout") and r.error:
+            blockers.append(f"[{r.node_id}] {r.error}")
+    return summary[:500], [], blockers
+
+
+def _node_summary_records(run) -> list[dict]:
+    """Project workflow node results into compact dicts for event logs."""
+    return [
+        {
+            "id": r.node_id,
+            "status": r.status,
+            "duration_ms": r.duration_ms,
+            "attempts": r.attempts,
+            "error": r.error,
+        }
+        for r in run.node_results
+    ]
+
+
+def _workflow_failure_state(
+    board: Board,
+    task: SchedulerTask,
+    existing_state: TaskState,
+    duration: int,
+    summary: str,
+    error: str,
+    workflow_name: str = "",
+    run_id: str = "",
+) -> TaskState:
+    """Persist a failure outcome when the workflow couldn't be loaded or never started."""
+    status = "failed"
+    _log_event(
+        "task_completed",
+        task=task.name,
+        session=task.session or "",
+        status=status,
+        duration=duration,
+        summary=summary,
+        files_modified=[],
+        blockers=[error] if error else [],
+        workflow=workflow_name or task.workflow,
+        run_id=run_id,
+        nodes=[],
+    )
+    _notify_portal(task.name, status, duration, summary)
+
+    new_run_count = existing_state.run_count + 1
+    new_state = TaskState(
+        last_run=datetime.now(timezone.utc),
+        last_status=status,
+        last_duration=duration,
+        run_count=new_run_count,
+        last_summary=summary,
+        last_gate_commit=_capture_head(task.project),
+    )
+
+    if task.max_runs is not None and new_run_count >= task.max_runs:
+        task.enabled = False
+        board.state[task.name] = new_state
+        save_board(board)
+        _log_event("task_disabled", task=task.name, reason="max_runs_reached",
+                   run_count=new_run_count, max_runs=task.max_runs)
+
+    return new_state
+
+
+def _dispatch_workflow_task(board: Board, task: SchedulerTask, existing_state: TaskState) -> TaskState:
+    """Dispatch a workflow task in-process via agentwire.workflows.runner.run_workflow."""
+    from agentwire.workflows.cli import RUNS_DIR
+    from agentwire.workflows.definitions import resolve_workflow
+    from agentwire.workflows.runner import run_workflow
+
+    start_time = time.time()
+
+    try:
+        wf = resolve_workflow(task.workflow)
+    except FileNotFoundError:
+        duration = int(time.time() - start_time)
+        return _workflow_failure_state(
+            board, task, existing_state, duration,
+            summary=f"{task.workflow} → failed: workflow not found",
+            error=f"workflow '{task.workflow}' not found",
+        )
+    except Exception as e:
+        duration = int(time.time() - start_time)
+        return _workflow_failure_state(
+            board, task, existing_state, duration,
+            summary=f"{task.workflow} → failed: {e}",
+            error=f"workflow load error: {e}",
+        )
+
+    rendered_inputs = _render_workflow_inputs(task.inputs, task)
+
+    try:
+        run = run_workflow(wf, runs_dir=RUNS_DIR, inputs=rendered_inputs, dry_run=False)
+    except Exception as e:
+        duration = int(time.time() - start_time)
+        return _workflow_failure_state(
+            board, task, existing_state, duration,
+            summary=f"{task.workflow} → failed: runner crashed",
+            error=f"runner crashed: {e}",
+            workflow_name=wf.name,
+        )
+
+    duration = int(time.time() - start_time)
+    status = _WORKFLOW_STATUS_TO_SCHED.get(run.status, "failed")
+    summary, files_modified, blockers = _parse_workflow_summary(run)
+
+    _log_event(
+        "task_completed",
+        task=task.name,
+        session=task.session or "",
+        status=status,
+        duration=duration,
+        summary=summary,
+        files_modified=files_modified,
+        blockers=blockers,
+        workflow=wf.name,
+        run_id=run.run_id,
+        nodes=_node_summary_records(run),
+    )
+
+    _notify_portal(task.name, status, duration, summary)
+
+    if task.project:
+        _auto_commit(task, task.name, status)
+
+    gate_commit = _capture_head(task.project)
 
     new_run_count = existing_state.run_count + 1
     new_state = TaskState(
@@ -1101,12 +1328,11 @@ def dispatch_task(board: Board, task_name: str) -> TaskState:
         last_gate_commit=gate_commit,
     )
 
-    # Auto-disable if max_runs reached
     if task.max_runs is not None and new_run_count >= task.max_runs:
         task.enabled = False
-        board.state[task_name] = new_state
+        board.state[task.name] = new_state
         save_board(board)
-        _log_event("task_disabled", task=task_name, reason="max_runs_reached",
+        _log_event("task_disabled", task=task.name, reason="max_runs_reached",
                    run_count=new_run_count, max_runs=task.max_runs)
 
     return new_state
@@ -1398,6 +1624,45 @@ def read_live_state() -> dict | None:
         return None
 
 
+def _validate_task_payload(name: str, task: SchedulerTask) -> list[str]:
+    """Validate the task vs workflow payload shape for a single task."""
+    errors: list[str] = []
+
+    has_workflow = bool(task.workflow)
+    has_task = bool(task.task)
+
+    if has_workflow and has_task:
+        errors.append(f"{name}: cannot set both 'task' and 'workflow'")
+    if not has_workflow and not has_task:
+        errors.append(f"{name}: must set either 'task' or 'workflow'")
+
+    if task.inputs and not has_workflow:
+        errors.append(f"{name}: 'inputs' only valid with 'workflow'")
+
+    if has_workflow:
+        try:
+            from agentwire.workflows.definitions import resolve_workflow
+            wf = resolve_workflow(task.workflow)
+        except FileNotFoundError:
+            errors.append(f"{name}: workflow '{task.workflow}' not found")
+            return errors
+        except Exception as e:
+            errors.append(f"{name}: workflow '{task.workflow}' could not be loaded: {e}")
+            return errors
+        wf_errors = wf.validate()
+        for err in wf_errors:
+            errors.append(f"{name}: workflow: {err}")
+
+    gate = task.gate or {}
+    if isinstance(gate, dict):
+        needs_project = bool(gate.get("git_commit") or gate.get("git_diff"))
+        if needs_project and not task.project:
+            gate_type = "git_commit" if gate.get("git_commit") else "git_diff"
+            errors.append(f"{name}: gate {gate_type} requires 'project' path")
+
+    return errors
+
+
 def validate_board(board: Board) -> list[str]:
     """Validate board configuration for errors.
 
@@ -1426,6 +1691,8 @@ def validate_board(board: Board) -> list[str]:
         if sched.after and sched.after in board.tasks and not board.tasks[sched.after].enabled:
             errors.append(f"{name}: warning: dependency '{sched.after}' is disabled")
 
+        errors.extend(_validate_task_payload(name, task))
+
     # Circular dependency detection via DFS
     def _has_cycle(start: str, visited: set, path: set) -> bool:
         if start in path:

{agentwire_dev-1.22.0 → agentwire_dev-1.23.0}/docs/scheduled-workloads.md

@@ -8,12 +8,32 @@ Reliable headless task execution for overnight and automated agent workflows.
 
 ## Overview
 
-Two primitives work together:
+Three paths for running scheduled work, picked per task:
 
-1. **`agentwire ensure`** — Reliable session management + task execution with lifecycle hooks
-2. **Tasks in `.agentwire.yml`** — Named workflows with pre/prompt/post phases and branch management
+1. **`agentwire ensure` tasks** — Reliable session management + task execution with lifecycle hooks. A full Claude Code session runs a single prompt from `.agentwire.yml`. Best for multi-step agent work that needs its own branch / PR / MCP tools.
+2. **Pi workflow tasks** — A YAML DAG of `pi -p --mode json` invocations runs in-process. No tmux session, no project required. Best for deterministic pipelines where each step has clear inputs/outputs and you want cheap per-node retries.
+3. **Tasks in `.agentwire.yml`** — Named tasks with pre/prompt/post phases and branch management — the substrate for path #1.
 
-For scheduled execution, combine with `~/.agentwire/scheduler.yaml` and the AgentWire scheduler daemon.
+All three are orchestrated by `~/.agentwire/scheduler.yaml` and the AgentWire scheduler daemon. A single board can mix ensure tasks and workflow tasks freely.
+
+---
+
+## Choosing ensure vs workflow
+
+| | ensure task | workflow task |
+|---|---|---|
+| Schedule field | `task: <name>` + `session:` | `workflow: <name-or-path>` + `inputs:` |
+| Dispatch | `agentwire ensure` subprocess → tmux session → Claude Code | `run_workflow()` in-process → pi subprocesses per node |
+| Model family | Claude (subscription via session type) | Z.AI glm-5 / flash-tier pi (per-node choice) |
+| Session needed | yes | no |
+| Project needed | yes (for branch mgmt) | optional (only for git gates / auto-commit) |
+| Multi-step logic | inside one Claude prompt | first-class DAG with retries, branches, outputs |
+| Dry-run | no | `scheduler run <name> --dry-run` prints the plan |
+| Cost profile | subscription-covered | Z.AI credits (or free flash tier) |
+
+A task must set exactly one of `task:` or `workflow:`. Everything else (gates, priority, `max_runs`, `once`, `cooldown`, `not_before`/`not_after`) applies to both.
+
+Full workflow task reference: [`docs/workflows.md#scheduler-integration`](workflows.md#scheduler-integration).
 
 ---