pcli-agent 0.1.0__py3-none-any.whl

pcli/sandbox/subprocess_backend.py

@@ -0,0 +1,376 @@
+"""Cross-platform fallback sandbox: process + filesystem containment via a
+cwd jail, a scrubbed environment, resource limits where the OS supports them,
+and a wall-clock timeout as the universal safety net.
+
+This backend does NOT provide network isolation on any platform — that
+requires Docker. Guardrails should treat network-sensitive tool calls as
+always-ask when this backend is active.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import subprocess
+import time
+import uuid
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pcli.sandbox.base import (
+    ExecRequest,
+    ExecResult,
+    Sandbox,
+    SandboxCapabilities,
+    SandboxSecurityError,
+)
+from pcli.sandbox.limits import is_posix, kill_process_tree, make_posix_preexec_fn
+
+_MAX_BACKGROUND_JOB_LIFETIME_S = 2 * 60 * 60
+_BACKGROUND_DRAIN_CHUNK_BYTES = 4096
+
+_ENV_ALLOW_NAMES = {
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "SYSTEMROOT",
+    "SYSTEMDRIVE",
+    "TEMP",
+    "TMP",
+    "LANG",
+    "LC_ALL",
+    "PATHEXT",
+    "COMSPEC",
+    "PYTHONIOENCODING",
+}
+_ENV_DENY_SUBSTRINGS = ("_KEY", "_TOKEN", "_SECRET", "_PASSWORD", "_CREDENTIAL", "_AUTH")
+
+
+def _scrub_env(extra: dict[str, str]) -> dict[str, str]:
+    env: dict[str, str] = {
+        name: value for name, value in os.environ.items() if name.upper() in _ENV_ALLOW_NAMES
+    }
+    for key, value in extra.items():
+        if any(pattern in key.upper() for pattern in _ENV_DENY_SUBSTRINGS):
+            continue
+        env[key] = value
+    return env
+
+
+def _is_relative_to(path: Path, other: Path) -> bool:
+    try:
+        path.relative_to(other)
+        return True
+    except ValueError:
+        return False
+
+
+def _truncate(data: bytes, max_bytes: int) -> str:
+    if len(data) <= max_bytes:
+        return data.decode(errors="replace")
+    return data[:max_bytes].decode(errors="replace") + "\n[...output truncated...]"
+
+
+async def _pump_stream(stream: asyncio.StreamReader, chunks: list[bytes]) -> None:
+    """Reads a stream into `chunks` (owned by the caller) as data arrives,
+    rather than accumulating in a local variable the way proc.communicate()
+    does — a coroutine cancelled mid-read (our own timeout, or the caller
+    cancelling the awaiting task) loses whatever's only in its own locals,
+    but `chunks` already holds everything read up to that point. Capping to
+    max_output_bytes is left to _truncate() on the joined result, same as
+    before this pumped-into-a-list approach replaced proc.communicate()."""
+    while True:
+        chunk = await stream.read(_BACKGROUND_DRAIN_CHUNK_BYTES)
+        if not chunk:
+            break
+        chunks.append(chunk)
+
+
+@dataclass
+class BackgroundJob:
+    """A command started via RestrictedSubprocessSandbox.start_background:
+    runs independently of any single tool call, with its stdout/stderr
+    continuously drained into memory (capped at max_output_bytes) so
+    read_background can report on it without blocking. stdout_read_offset/
+    stderr_read_offset track how much of each stream a caller has already
+    consumed (see read_background) — new reads only return what's arrived
+    since the last one, rather than re-sending everything or silently
+    dropping whatever fell outside a fixed tail window."""
+
+    id: str
+    command: str
+    started_at: float
+    proc: asyncio.subprocess.Process
+    stdout_chunks: list[bytes] = field(default_factory=list)
+    stderr_chunks: list[bytes] = field(default_factory=list)
+    stdout_bytes: int = 0
+    stderr_bytes: int = 0
+    stdout_read_offset: int = 0
+    stderr_read_offset: int = 0
+    exit_code: int | None = None
+    finished_at: float | None = None
+
+    @property
+    def running(self) -> bool:
+        return self.exit_code is None
+
+
+class RestrictedSubprocessSandbox(Sandbox):
+    name = "subprocess"
+
+    def __init__(
+        self,
+        *,
+        allowed_roots: list[Path] | None = None,
+        max_output_bytes: int = 2_000_000,
+        cpu_seconds: int | None = 30,
+        memory_bytes: int | None = None,
+    ) -> None:
+        # memory_bytes defaults to None (no RLIMIT_AS): confirmed real case
+        # - RLIMIT_AS bounds *virtual* address space, not actual usage, and
+        # Go's runtime (kubectl, terraform, most Go-based CLIs - exactly
+        # what toolbox exists to wrap) routinely reserves well past a few
+        # hundred MB of virtual space at startup regardless of real RSS, so
+        # the old 512MB default made ordinary tool invocations fail
+        # outright. RLIMIT_RSS is advisory/unenforced on modern Linux, and
+        # RLIMIT_DATA only bounds sbrk allocation, which mmap-based
+        # allocators (Go's included) bypass - neither is a real fix. This
+        # backend's actual safety net is (and always was, per limits.py's
+        # own docstring) the wall-clock timeout + kill_process_tree, the
+        # same on every platform; cpu_seconds doesn't share this false-
+        # positive problem (a large virtual reservation burns no CPU time)
+        # and stays on by default. Both are still constructor overrides -
+        # see Settings.sandbox_memory_limit_bytes/sandbox_cpu_limit_s
+        # (agent/runtime.py) - for anyone who deliberately wants a memory
+        # cap, e.g. on a constrained VM.
+        self._allowed_roots = [p.expanduser().resolve() for p in (allowed_roots or [Path.cwd()])]
+        self._max_output_bytes = max_output_bytes
+        self._cpu_seconds = cpu_seconds
+        self._memory_bytes = memory_bytes
+        self._background_jobs: dict[str, BackgroundJob] = {}
+
+    def capabilities(self) -> SandboxCapabilities:
+        posix = is_posix()
+        return SandboxCapabilities(
+            supports_network_isolation=False,
+            supports_memory_limit=posix,
+            supports_cpu_limit=posix,
+        )
+
+    def _validate_cwd(self, cwd: Path) -> Path:
+        resolved = cwd.expanduser().resolve()
+        for root in self._allowed_roots:
+            if resolved == root or _is_relative_to(resolved, root):
+                return resolved
+        raise SandboxSecurityError(f"cwd '{resolved}' is outside all allowed roots")
+
+    def _popen_kwargs(self) -> dict:
+        if is_posix():
+            return {
+                "preexec_fn": make_posix_preexec_fn(
+                    cpu_seconds=self._cpu_seconds, memory_bytes=self._memory_bytes
+                ),
+                "start_new_session": True,
+            }
+        return {"creationflags": subprocess.CREATE_NEW_PROCESS_GROUP}
+
+    async def _start_process(
+        self, command: list[str] | str, cwd: Path, env: dict[str, str], *, needs_stdin: bool
+    ) -> asyncio.subprocess.Process:
+        popen_kwargs = self._popen_kwargs()
+        stdin_mode = asyncio.subprocess.PIPE if needs_stdin else asyncio.subprocess.DEVNULL
+        if isinstance(command, str):
+            return await asyncio.create_subprocess_shell(
+                command,
+                cwd=str(cwd),
+                env=env,
+                stdin=stdin_mode,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                **popen_kwargs,
+            )
+        return await asyncio.create_subprocess_exec(
+            *command,
+            cwd=str(cwd),
+            env=env,
+            stdin=stdin_mode,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+            **popen_kwargs,
+        )
+
+    async def execute(self, request: ExecRequest) -> ExecResult:
+        cwd = self._validate_cwd(request.cwd)
+        env = _scrub_env(request.env)
+        proc = await self._start_process(
+            request.command, cwd, env, needs_stdin=request.stdin is not None
+        )
+
+        timed_out = False
+        stdin_bytes = request.stdin.encode() if request.stdin is not None else None
+        stdout_chunks: list[bytes] = []
+        stderr_chunks: list[bytes] = []
+        # Pumped via separate tasks (not proc.communicate()) specifically so
+        # a timeout/cancellation below still leaves whatever was already
+        # read sitting in stdout_chunks/stderr_chunks — communicate() would
+        # discard it all, since its accumulated bytes live in a coroutine
+        # local that's thrown away when the coroutine is cancelled.
+        stdout_task = asyncio.ensure_future(_pump_stream(proc.stdout, stdout_chunks))
+        stderr_task = asyncio.ensure_future(_pump_stream(proc.stderr, stderr_chunks))
+        try:
+            if stdin_bytes is not None:
+                proc.stdin.write(stdin_bytes)
+                await proc.stdin.drain()
+            if proc.stdin is not None:
+                proc.stdin.close()
+            await asyncio.wait_for(
+                asyncio.gather(stdout_task, stderr_task, proc.wait()),
+                timeout=request.timeout_s,
+            )
+        except TimeoutError:
+            timed_out = True
+            kill_process_tree(proc.pid)
+            stdout_task.cancel()
+            stderr_task.cancel()
+            try:
+                await asyncio.wait_for(proc.wait(), timeout=5)
+            except TimeoutError:
+                pass
+        except asyncio.CancelledError:
+            # Distinct from the TimeoutError case above: this fires when the
+            # *caller* (e.g. the TUI's Esc+Esc turn cancellation) cancels the
+            # awaiting task, not when our own wait_for's timeout expires.
+            # Without this, the subprocess is silently orphaned — cancelling
+            # the Python await here does nothing to the OS process itself.
+            kill_process_tree(proc.pid)
+            stdout_task.cancel()
+            stderr_task.cancel()
+            raise
+
+        stdout_bytes = b"".join(stdout_chunks)
+        stderr_bytes = b"".join(stderr_chunks)
+        if timed_out:
+            note = b"[pcli] command timed out and was killed"
+            stderr_bytes = stderr_bytes + b"\n" + note if stderr_bytes else note
+
+        return ExecResult(
+            stdout=_truncate(stdout_bytes, self._max_output_bytes),
+            stderr=_truncate(stderr_bytes, self._max_output_bytes),
+            exit_code=proc.returncode if proc.returncode is not None else -1,
+            timed_out=timed_out,
+            backend_used=self.name,
+        )
+
+    # --- Background jobs: run_shell_background/read_background_output/
+    # stop_background_process (tools/builtin/shell_tool.py) sit on top of
+    # these. Deliberately not part of the Sandbox ABC (see plan) - kept here
+    # so DockerSandbox/NullSandbox don't need to implement something they
+    # can't meaningfully support yet; callers duck-type-check
+    # isinstance(sandbox, RestrictedSubprocessSandbox).
+
+    async def _pump_background_stream(
+        self, stream: asyncio.StreamReader, job: BackgroundJob, attr: str
+    ) -> None:
+        chunks: list[bytes] = getattr(job, f"{attr}_chunks")
+        while True:
+            chunk = await stream.read(_BACKGROUND_DRAIN_CHUNK_BYTES)
+            if not chunk:
+                break
+            current = getattr(job, f"{attr}_bytes")
+            if current < self._max_output_bytes:
+                chunks.append(chunk[: self._max_output_bytes - current])
+            setattr(job, f"{attr}_bytes", current + len(chunk))
+
+    async def _drain_background(self, job: BackgroundJob) -> None:
+        await asyncio.gather(
+            self._pump_background_stream(job.proc.stdout, job, "stdout"),
+            self._pump_background_stream(job.proc.stderr, job, "stderr"),
+        )
+        job.exit_code = await job.proc.wait()
+        job.finished_at = time.monotonic()
+
+    def _sweep_background_jobs(self, *, keep_finished: int = 20) -> None:
+        now = time.monotonic()
+        for job in list(self._background_jobs.values()):
+            if job.running and now - job.started_at > _MAX_BACKGROUND_JOB_LIFETIME_S:
+                kill_process_tree(job.proc.pid)
+        finished = sorted(
+            (j for j in self._background_jobs.values() if not j.running),
+            key=lambda j: j.finished_at or 0.0,
+        )
+        while len(self._background_jobs) > keep_finished and finished:
+            del self._background_jobs[finished.pop(0).id]
+
+    async def start_background(
+        self,
+        *,
+        command: list[str] | str,
+        cwd: Path,
+        env: dict[str, str] | None = None,
+        max_jobs: int = 5,
+    ) -> str:
+        self._sweep_background_jobs()
+        running = sum(1 for job in self._background_jobs.values() if job.running)
+        if running >= max_jobs:
+            raise SandboxSecurityError(
+                f"Already {running} background job(s) running (max {max_jobs}) — stop one "
+                "with stop_background_process before starting another."
+            )
+        resolved_cwd = self._validate_cwd(cwd)
+        scrubbed_env = _scrub_env(env or {})
+        proc = await self._start_process(command, resolved_cwd, scrubbed_env, needs_stdin=False)
+        job_id = uuid.uuid4().hex[:8]
+        command_str = command if isinstance(command, str) else " ".join(command)
+        job = BackgroundJob(id=job_id, command=command_str, started_at=time.monotonic(), proc=proc)
+        self._background_jobs[job_id] = job
+        asyncio.create_task(self._drain_background(job))
+        return job_id
+
+    def get_background(self, job_id: str) -> BackgroundJob | None:
+        return self._background_jobs.get(job_id)
+
+    def read_background(
+        self, job_id: str, *, max_chars: int = 4000, reset: bool = False
+    ) -> tuple[BackgroundJob, str, str, bool] | None:
+        """Returns (job, new_stdout, new_stderr, has_more): only the text
+        that arrived since the caller's last read (or from the start, if
+        reset or this is the first read), capped to max_chars per stream
+        per call — offset-based rather than tail-based, so nothing in the
+        middle is silently dropped between polls on a chatty command; a
+        caller wanting more just calls again (has_more says so) instead of
+        requesting a bigger max_chars, so one poll can't flood context."""
+        job = self._background_jobs.get(job_id)
+        if job is None:
+            return None
+        if reset:
+            job.stdout_read_offset = 0
+            job.stderr_read_offset = 0
+        full_stdout = b"".join(job.stdout_chunks).decode(errors="replace")
+        full_stderr = b"".join(job.stderr_chunks).decode(errors="replace")
+        new_stdout = full_stdout[job.stdout_read_offset :]
+        new_stderr = full_stderr[job.stderr_read_offset :]
+        stdout_chunk = new_stdout[:max_chars]
+        stderr_chunk = new_stderr[:max_chars]
+        job.stdout_read_offset += len(stdout_chunk)
+        job.stderr_read_offset += len(stderr_chunk)
+        has_more = len(new_stdout) > len(stdout_chunk) or len(new_stderr) > len(stderr_chunk)
+        return job, stdout_chunk, stderr_chunk, has_more
+
+    async def stop_background(self, job_id: str) -> bool:
+        job = self._background_jobs.get(job_id)
+        if job is None:
+            return False
+        if job.running:
+            kill_process_tree(job.proc.pid)
+            try:
+                await asyncio.wait_for(job.proc.wait(), timeout=5)
+            except TimeoutError:
+                pass
+        return True
+
+    async def kill_all_background_jobs(self) -> None:
+        """Called from ChatScreen.on_unmount so a background job never
+        outlives the TUI process it was started from."""
+        for job in list(self._background_jobs.values()):
+            if job.running:
+                kill_process_tree(job.proc.pid)

pcli/scheduler/daemon.py

@@ -0,0 +1,194 @@
+"""The long-running loop behind `pcli schedule run` - the third kind of
+daemon alongside `pcli telegram`'s (telegram/daemon.py) and the browser
+session's own lazy lifecycle. Ticks on a plain poll interval (no OS-level
+cron integration, no extra process) - see scheduler/models.py's ScheduleJob
+for what a job stores and scheduler/runner.py's run_task_once for how one
+actually executes, shared with `pcli run`.
+
+croniter is imported lazily inside the two functions that need it, not at
+this module's top level, so `import pcli.scheduler.daemon` itself doesn't
+require the `schedule` extra to be installed - only actually computing a
+next-run time does (mirrors browser/session.py's lazy playwright import and
+telegram/sender.py's lazy python-telegram-bot import)."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable
+from datetime import UTC, datetime
+from pathlib import Path
+
+from pcli.agent.headless import HeadlessTurnResult
+from pcli.config.settings import Settings
+from pcli.scheduler.models import ScheduleJob
+from pcli.scheduler.runner import ScheduledSessionNotFoundError, run_task_once
+from pcli.scheduler.store import read_schedule, update_job
+from pcli.scheduler.triggers import compute_path_signature, get_git_head_sha
+from pcli.session.store import SessionStore
+
+logger = logging.getLogger(__name__)
+
+OnTickCallback = Callable[[], None]
+OnJobRunCallback = Callable[[ScheduleJob, "HeadlessTurnResult | None", Exception | None], None]
+
+
+def compute_next_run(cron: str, *, base: datetime) -> datetime:
+    from croniter import croniter
+
+    return croniter(cron, base).get_next(datetime)
+
+
+async def run_scheduler_daemon(
+    settings: Settings,
+    *,
+    poll_interval_s: int = 30,
+    on_tick: OnTickCallback | None = None,
+    on_job_run: OnJobRunCallback | None = None,
+) -> None:
+    """Runs until cancelled (Ctrl+C from `pcli schedule run`, or the caller
+    cancelling the task). Each tick re-reads schedule.json fresh (see
+    scheduler/store.py's read_schedule), so `pcli schedule add`/`remove`/
+    `enable`/`disable` run from another process take effect on the very
+    next tick without restarting this daemon. Jobs run sequentially within
+    a tick - simple, predictable, and avoids overlapping runs of possibly-
+    related scheduled tasks competing for the same sandbox/session."""
+    store = SessionStore()
+    cwd = Path.cwd()
+    while True:
+        await _run_due_jobs(settings, store, cwd, on_job_run=on_job_run)
+        if on_tick is not None:
+            on_tick()
+        await asyncio.sleep(poll_interval_s)
+
+
+def _cron_due(job: ScheduleJob, now: datetime) -> bool:
+    if job.next_run_at is None:
+        assert job.cron is not None  # enforced by ScheduleJob's validator
+        job.next_run_at = compute_next_run(job.cron, base=now)
+        update_job(job)
+        return False
+    return job.next_run_at <= now
+
+
+def _current_event_signature(job: ScheduleJob, cwd: Path) -> str | None:
+    if job.trigger == "file_change":
+        assert job.watch_path is not None  # enforced by ScheduleJob's validator
+        return compute_path_signature(Path(job.watch_path))
+    assert job.trigger == "git_commit"
+    repo = Path(job.watch_git_repo) if job.watch_git_repo else cwd
+    return get_git_head_sha(repo, job.watch_git_branch)
+
+
+def _event_due(job: ScheduleJob, cwd: Path) -> bool:
+    signature = _current_event_signature(job, cwd)
+    if signature is None:
+        # A git lookup failed this poll (repo not there yet, git missing,
+        # ...) - already logged in triggers.py. Just skip and retry next
+        # tick rather than marking the job an error.
+        return False
+    if job.last_seen_state is None:
+        # First time this job's been seen by any poll - baseline without
+        # firing, the same "compute and skip" first-tick behavior cron
+        # jobs get above, so adding a job against an already-existing
+        # file/commit doesn't fire immediately.
+        job.last_seen_state = signature
+        update_job(job)
+        return False
+    return signature != job.last_seen_state
+
+
+def _rebaseline_event_job(job: ScheduleJob, cwd: Path) -> None:
+    """Re-reads the current signature *after* the job's own run finished
+    and stores that as the new baseline - deliberately not the signature
+    that triggered the run. Otherwise a task that itself edits the watched
+    path, or commits to the watched branch (a very plausible case - e.g. a
+    task that auto-commits its own changes), would see its own output as
+    "one more change" on the very next poll and fire again indefinitely.
+    Baselining after the run means only changes introduced *after* the
+    job's own run completed count as the next trigger."""
+    signature = _current_event_signature(job, cwd)
+    if signature is not None:
+        job.last_seen_state = signature
+        update_job(job)
+
+
+async def _run_due_jobs(
+    settings: Settings,
+    store: SessionStore,
+    cwd: Path,
+    *,
+    on_job_run: OnJobRunCallback | None,
+) -> None:
+    now = datetime.now(UTC)
+    for job in read_schedule().jobs:
+        if not job.enabled:
+            continue
+        is_due = _cron_due(job, now) if job.trigger == "cron" else _event_due(job, cwd)
+        if not is_due:
+            continue
+        await _run_one_job(job, settings, store, cwd, on_job_run=on_job_run)
+        if job.trigger != "cron":
+            _rebaseline_event_job(job, cwd)
+
+
+async def _run_one_job(
+    job: ScheduleJob,
+    settings: Settings,
+    store: SessionStore,
+    cwd: Path,
+    *,
+    on_job_run: OnJobRunCallback | None,
+) -> None:
+    task = job.task
+    if job.task_file:
+        task = Path(job.task_file).read_text(encoding="utf-8")
+    assert task is not None  # ScheduleJob guarantees exactly one of task/task_file is set
+
+    job_settings = settings
+    if job.max_cost_usd is not None:
+        # A local override for just this job's own runs, same reasoning as
+        # `pcli run --max-cost` (cli.py's run_command) - never mutates the
+        # shared settings object other jobs/the daemon loop itself use.
+        job_settings = settings.model_copy(update={"max_session_cost_usd": job.max_cost_usd})
+    if job.audit:
+        job_settings = job_settings.model_copy(update={"audit_mode_enabled": True})
+
+    result: HeadlessTurnResult | None = None
+    error: Exception | None = None
+    try:
+        result = await run_task_once(
+            task,
+            settings=job_settings,
+            store=store,
+            cwd=cwd,
+            session_id=job.session_id,
+            quiet=job.quiet,
+            headed=job.headed,
+            notify_telegram_flag=job.notify_telegram,
+        )
+        job.last_status = "ok"
+        job.last_error = None
+    except ScheduledSessionNotFoundError as exc:
+        error = exc
+        job.last_status = "error"
+        job.last_error = f"session '{job.session_id}' no longer exists"
+        logger.error(
+            "Scheduled job %s (%s): %s", job.id, job.name or job.cron or job.trigger, job.last_error
+        )
+    except Exception as exc:  # one job failing must not kill the daemon loop
+        error = exc
+        job.last_status = "error"
+        job.last_error = str(exc)
+        logger.exception(
+            "Scheduled job %s (%s) failed", job.id, job.name or job.cron or job.trigger
+        )
+
+    job.last_run_at = datetime.now(UTC)
+    if job.trigger == "cron":
+        assert job.cron is not None  # enforced by ScheduleJob's validator
+        job.next_run_at = compute_next_run(job.cron, base=job.last_run_at)
+    update_job(job)
+
+    if on_job_run is not None:
+        on_job_run(job, result, error)

pcli/scheduler/models.py

@@ -0,0 +1,97 @@
+"""Data model for `pcli schedule`'s crontab-like recurring task scheduling -
+see scheduler/store.py for persistence, scheduler/runner.py for how a job
+actually executes (shared with `pcli run`), and scheduler/daemon.py for the
+loop that decides when a job is due."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, model_validator
+
+from pcli.util.ids import new_id
+
+
+def _utcnow() -> datetime:
+    return datetime.now(UTC)
+
+
+class ScheduleJob(BaseModel):
+    id: str = Field(default_factory=lambda: new_id("job_"))
+    name: str = ""
+    trigger: Literal["cron", "file_change", "git_commit"] = "cron"
+    """Defaults to "cron" so every job already persisted in an existing
+    schedule.json (written before this field existed) still validates and
+    behaves exactly as before - see the model_validator below for what
+    each trigger kind requires."""
+    cron: str | None = None
+    """Standard 5-field cron expression (minute hour day month weekday),
+    e.g. "*/15 * * * *". Required (and validated via croniter.is_valid
+    before a job is ever saved - see scheduler/store.py's add_job) when
+    trigger == "cron"; otherwise unused."""
+    watch_path: str | None = None
+    """trigger == "file_change" only: a file or directory (watched
+    recursively) whose contents/mtimes are polled for changes - see
+    scheduler/triggers.py's compute_path_signature."""
+    watch_git_repo: str | None = None
+    """trigger == "git_commit" only: path to the repo to watch, defaulting
+    to the daemon's own cwd if unset."""
+    watch_git_branch: str | None = None
+    """trigger == "git_commit" only: branch to watch, defaulting to
+    whatever's currently checked out (bare HEAD) if unset."""
+    last_seen_state: str | None = None
+    """trigger in ("file_change", "git_commit") only: the signature/commit
+    SHA last observed by the daemon (scheduler/triggers.py), used to
+    detect a change on the next poll. None means "never polled yet" - the
+    daemon baselines it on first sight without firing, the same way a
+    cron job's unset next_run_at is computed-then-skipped on first sight
+    rather than firing immediately."""
+    task: str | None = None
+    task_file: str | None = None
+    """Exactly one of task/task_file is set - mirrors `pcli run`'s own
+    --task/--task-file mutual exclusivity."""
+    session_id: str | None = None
+    """Append to this one continuing session on every run, or None for a
+    fresh session each time - mirrors `pcli run --session`."""
+    headed: bool = False
+    notify_telegram: bool = False
+    quiet: bool = True
+    max_cost_usd: float | None = None
+    """Per-job hard spend cap (USD), overriding Settings.max_session_cost_usd
+    for just this job's own runs - mirrors `pcli run --max-cost`, applied the
+    same way (scheduler/daemon.py's _run_one_job): never persisted to
+    config.toml, never affects other jobs or the TUI. None (the default)
+    means this job falls back to whatever max_session_cost_usd is already
+    configured (unset by default - no cap)."""
+    audit: bool = False
+    """Per-job override of Settings.audit_mode_enabled, applied the same
+    way as max_cost_usd above - mirrors `pcli run --audit`. False (the
+    default) means this job falls back to whatever audit_mode_enabled is
+    already configured (off by default)."""
+    enabled: bool = True
+    created_at: datetime = Field(default_factory=_utcnow)
+    next_run_at: datetime | None = None
+    """Computed lazily by the daemon on first seeing a job with this unset
+    (or after it fires) via croniter(cron, base=...).get_next(datetime) -
+    not computed at job-creation time so a job added while the daemon isn't
+    running doesn't carry a stale "next run" from whenever `schedule add`
+    happened to execute."""
+    last_run_at: datetime | None = None
+    last_status: str | None = None
+    """"ok" or "error" after the most recent run; None if it has never run."""
+    last_error: str | None = None
+
+    @model_validator(mode="after")
+    def _validate_trigger_fields(self) -> ScheduleJob:
+        if self.trigger == "cron" and not self.cron:
+            raise ValueError("trigger 'cron' requires cron to be set.")
+        if self.trigger == "file_change" and not self.watch_path:
+            raise ValueError("trigger 'file_change' requires watch_path to be set.")
+        # "git_commit" has no required field: watch_git_repo/watch_git_branch
+        # both default sensibly (daemon's cwd / whatever's checked out).
+        return self
+
+
+class ScheduleStore(BaseModel):
+    jobs: list[ScheduleJob] = Field(default_factory=list)