jobctrl 0.3.1__tar.gz → 0.4.0__tar.gz

jobctrl-0.4.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.5
+Name: jobctrl
+Version: 0.4.0
+Summary: AI-powered end-to-end job application pipeline
+Project-URL: Homepage, https://github.com/ebarti/JobCtrl
+Project-URL: Repository, https://github.com/ebarti/JobCtrl
+Project-URL: Issues, https://github.com/ebarti/JobCtrl/issues
+Author: Eloi Barti
+License-Expression: AGPL-3.0-only
+Keywords: ai,apply,automation,job-application,job-search,resume
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: GNU Affero General Public License v3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Requires-Python: >=3.11
+Requires-Dist: agent-runtime-kit<0.6,>=0.5.4
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: certifi>=2026.10.19
+Requires-Dist: click>=8.3.3
+Requires-Dist: httpx>=0.24
+Requires-Dist: jobstreaming==0.0.5
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0
+Requires-Dist: opentelemetry-sdk>=1.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: playwright>=1.40
+Requires-Dist: publicsuffix2<3,>=2.20191221
+Requires-Dist: pydantic>=2.10
+Requires-Dist: pypdf>=6.14.2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: temporalio>=1.31
+Requires-Dist: typer>=0.9.0
+Requires-Dist: ua-generator>=2.1.7
+Requires-Dist: websocket-client>=1.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: cryptography>=50.0.0; extra == 'dev'
+Requires-Dist: google-auth>=2.0; extra == 'dev'
+Requires-Dist: hatchling==1.32.4; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-randomly>=4.0; extra == 'dev'
+Requires-Dist: pytest-timeout<3,>=2.4; extra == 'dev'
+Requires-Dist: pytest-xdist<4,>=3.8; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: python-docx<2,>=1.2; extra == 'dev'
+Requires-Dist: ruff==0.17.1; extra == 'dev'
+Provides-Extra: providers
+Requires-Dist: claude-agent-sdk==0.2.121; extra == 'providers'
+Requires-Dist: google-antigravity==0.1.2; extra == 'providers'
+Requires-Dist: mcp>=1.28.1; extra == 'providers'
+Requires-Dist: openai-codex-cli-bin==0.163.0; extra == 'providers'
+Requires-Dist: openai-codex==0.163.0; extra == 'providers'
+Requires-Dist: pyasn1>=0.6.4; extra == 'providers'
+Description-Content-Type: text/markdown
+
+# JobCtrl Automation Worker
+
+This package contains JobCtrl's Python automation engine and CLI. It owns job
+discovery, enrichment, scoring, tailoring, cover letters, PDF generation,
+profile import, and local browser apply automation.
+
+Use it from the repository root through `uv`:
+
+```bash
+uv --project workers/automation run jobctrl doctor
+uv --project workers/automation run jobctrl run
+uv --project workers/automation run jobctrl worker
+```
+
+The full local application is normally started from the repository root with
+`corepack pnpm dev`, which runs Temporal, the TypeScript API, the React web app, and this
+worker together.
+
+Provider generation runs through `agent-runtime-kit`. The worker owns the
+persistent async service and idle runtime cache; provider SDKs remain optional
+source/runtime packs. See `docs/architecture/agent-runtime.md` for request
+isolation, reuse, permissions and shutdown.
+
+Useful docs:
+
+- root `README.md` for the public overview and quick start;
+- `docs/user/getting-started.md` for setup and local stack commands;
+- `docs/user/configuration.md` for environment variables;
+- `docs/architecture/` and `docs/architecture/pipeline/` for internal
+  runtime ownership.
+
+Profile data, generated materials, browser state, logs, and SQLite databases
+are sensitive local artifacts. Do not commit them or include them in public bug
+reports.

jobctrl-0.4.0/README.md

@@ -0,0 +1,34 @@
+# JobCtrl Automation Worker
+
+This package contains JobCtrl's Python automation engine and CLI. It owns job
+discovery, enrichment, scoring, tailoring, cover letters, PDF generation,
+profile import, and local browser apply automation.
+
+Use it from the repository root through `uv`:
+
+```bash
+uv --project workers/automation run jobctrl doctor
+uv --project workers/automation run jobctrl run
+uv --project workers/automation run jobctrl worker
+```
+
+The full local application is normally started from the repository root with
+`corepack pnpm dev`, which runs Temporal, the TypeScript API, the React web app, and this
+worker together.
+
+Provider generation runs through `agent-runtime-kit`. The worker owns the
+persistent async service and idle runtime cache; provider SDKs remain optional
+source/runtime packs. See `docs/architecture/agent-runtime.md` for request
+isolation, reuse, permissions and shutdown.
+
+Useful docs:
+
+- root `README.md` for the public overview and quick start;
+- `docs/user/getting-started.md` for setup and local stack commands;
+- `docs/user/configuration.md` for environment variables;
+- `docs/architecture/` and `docs/architecture/pipeline/` for internal
+  runtime ownership.
+
+Profile data, generated materials, browser state, logs, and SQLite databases
+are sensitive local artifacts. Do not commit them or include them in public bug
+reports.

jobctrl-0.4.0/pyproject.toml

@@ -0,0 +1,158 @@
+[project]
+name = "jobctrl"
+version = "0.4.0"
+description = "AI-powered end-to-end job application pipeline"
+readme = "README.md"
+license = "AGPL-3.0-only"
+requires-python = ">=3.11"
+authors = [{ name = "Eloi Barti" }]
+keywords = ["job-search", "automation", "ai", "resume", "apply", "job-application"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "License :: OSI Approved :: GNU Affero General Public License v3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+]
+
+dependencies = [
+    # Shared lifecycle, capability and process-reuse boundary for agent SDKs.
+    "agent-runtime-kit>=0.5.4,<0.6",
+    "certifi>=2026.10.19",
+    "typer>=0.9.0",
+    "click>=8.3.3",
+    "rich>=13.0",
+    "httpx>=0.24",
+    "websocket-client>=1.8",
+    "beautifulsoup4>=4.12",
+    "playwright>=1.40",
+    "python-dotenv>=1.0",
+    "pypdf>=6.14.2",
+    "pyyaml>=6.0",
+    "pandas>=2.0",
+    # 1.31 includes the cancellation/shield fix, while retaining activity
+    # cancellation details and run IDs used by enrichment ownership fencing.
+    "temporalio>=1.31",
+    "opentelemetry-api>=1.27",
+    "opentelemetry-sdk>=1.27",
+    "opentelemetry-exporter-otlp-proto-http>=1.27",
+    "opentelemetry-instrumentation-httpx>=0.48b0",
+    # Typed, concurrent job-board events plus resumable checkpoints. Pin the
+    # integration contract so JobCtrl's durable adapter changes deliberately.
+    "jobstreaming==0.0.5",
+    # Pydantic backs the canonical employer-analysis domain model
+    # (``domain/materials/analysis.py``) and is also pulled transitively by
+    # the agent SDKs below. Declared explicitly because the domain layer
+    # imports it directly.
+    "pydantic>=2.10",
+    # Gmail verification scopes derive sender domains from application URLs and
+    # need public-suffix-aware eTLD+1 parsing.
+    "publicsuffix2>=2.20191221,<3",
+    "ua-generator>=2.1.7",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2",
+    "cryptography>=50.0.0",
+    "google-auth>=2.0",
+    "hatchling==1.32.4",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23",
+    "pytest-randomly>=4.0",
+    "pytest-timeout>=2.4,<3",
+    "pytest-xdist>=3.8,<4",
+    "python-docx>=1.2,<2",
+    "ruff==0.17.1",
+]
+providers = [
+    "claude-agent-sdk==0.2.121",
+    "mcp>=1.28.1",
+    "openai-codex==0.163.0",
+    "openai-codex-cli-bin==0.163.0",
+    "google-antigravity==0.1.2",
+    "pyasn1>=0.6.4",
+]
+
+# Source checkouts keep the provider ensemble available on ordinary `uv sync`
+# and `uv run`. Production payload builders use `--no-default-groups --no-dev`
+# and acquire provider wheels separately through the signed provider-pack path.
+[dependency-groups]
+provider-runtime = [
+    "claude-agent-sdk==0.2.121",
+    "openai-codex==0.163.0",
+    "openai-codex-cli-bin==0.163.0",
+    "google-antigravity==0.1.2",
+]
+release-build = ["build==1.6.1", "hatchling==1.32.4"]
+# The always-on privacy gate uses only this locked tool slice; it must not
+# resolve an independent floating pytest environment on every pull request.
+release-check = ["pytest>=7.0"]
+
+[project.scripts]
+jobctrl = "jobctrl.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/ebarti/JobCtrl"
+Repository = "https://github.com/ebarti/JobCtrl"
+Issues = "https://github.com/ebarti/JobCtrl/issues"
+
+[build-system]
+# Release builds run with --no-isolation, so both the build backend and the
+# locked development environment must resolve this exact, audited backend.
+requires = ["hatchling==1.32.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jobctrl"]
+
+[tool.hatch.build]
+artifacts = ["src/jobctrl/config/*.yaml", "src/jobctrl/assets/fonts/*", "src/jobctrl/assets/interview/*.json", "src/jobctrl/assets/determinations/*.json", "src/jobctrl/infrastructure/migrations/*.sql"]
+
+[tool.hatch.build.targets.sdist.force-include]
+"../../LICENSE" = "LICENSE"
+"../../NOTICE" = "NOTICE"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+# Preserve the existing project policy across Ruff default-rule changes.
+select = ["E4", "E7", "E9", "F"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+tmp_path_retention_policy = "failed"
+# "thread" dumps every thread's stack at the bound and hard-exits the process.
+# "signal" raised only in the main thread and could not unwind a worker-pool
+# thread blocked in a SQLite BEGIN IMMEDIATE wait, which wedged the lane for
+# its whole job ceiling (run 32481181792, Python 3.11). faulthandler stays as
+# the slightly later second-chance dump if pytest-timeout itself fails.
+faulthandler_timeout = 240
+timeout = 180
+timeout_method = "thread"
+markers = [
+    "core: hermetic tests that do not own a Temporal test server or migration fixture",
+    "migration: database migration and copy tests routed to memory-backed CI storage",
+    "system_browser: opt-in smoke requiring a real local system Chrome/Chromium; set JOBCTRL_RUN_SYSTEM_BROWSER_TESTS=1",
+    "temporal: tests whose file owns a Temporal WorkflowEnvironment lifecycle",
+]
+
+[tool.pyright]
+venvPath = "."
+venv = ".venv"
+extraPaths = ["src"]
+include = ["src", "tests"]
+pythonVersion = "3.11"
+
+[tool.uv]
+default-groups = ["provider-runtime"]
+
+# Dependabot owns the rolling community-vetting delay. Keeping that delay here
+# as a relative timestamp would make an unchanged lockfile fail `uv --locked`
+# as time passes. Provider runtimes and the audited JobStreaming integration
+# retain their explicit reviewed cutoffs.
+exclude-newer-package = { "google-antigravity" = "2026-06-04T21:19:27Z", "claude-agent-sdk" = "2026-07-18T00:00:00Z", "jobstreaming" = "2026-08-29T23:59:59Z" }

jobctrl-0.4.0/src/jobctrl/__init__.py

@@ -0,0 +1,3 @@
+"""JobCtrl — AI-powered end-to-end job application pipeline."""
+
+__version__ = "0.4.0"

jobctrl-0.4.0/src/jobctrl/apply/activities.py

@@ -0,0 +1,197 @@
+"""Temporal activity for the apply stage."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import Any
+
+from temporalio import activity
+from temporalio.exceptions import ApplicationError
+
+from jobctrl.domain.identifiers import JobId, canonical_job_id
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class ApplyActivityInput:
+    # Every targeted claim is scoped by this tenant and canonical JobId.
+    tenant_id: str
+    expected_app_dir: str | None = None
+    expected_db_path: str | None = None
+    job_id: JobId | None = None
+    limit: int = 1
+    min_score: int = 7
+    model: str = "default"
+    headless: bool = False
+    dry_run: bool = False
+    workers: int = 1
+    approval_required: bool = True
+    # Run-forever poll mode — when True, the activity calls ``apply_main``
+    # with ``limit=0`` (the launcher's run-forever sentinel) and ignores
+    # ``limit``.  Otherwise ``max(1, limit)`` jobs are processed.
+    continuous: bool = False
+    auto_apply_loop: bool = False
+    # Bounded batches belonging to a standing workflow are polls, not manual retries.
+    standing_refusal_poll: bool = False
+    dispatch_frontier: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.job_id is not None:
+            object.__setattr__(self, "job_id", canonical_job_id(str(self.job_id)))
+
+
+@dataclass(frozen=True)
+class ApplyActivityOutput:
+    status: str
+    applied: int
+    failed: int
+    error: str | None = None
+    # Older activity histories have no worker-crash observation.
+    worker_crashes: int | None = None
+    # Only refusals with a durable refund and completed owner settlement count.
+    settled_refusals: int | None = None
+
+
+@dataclass(frozen=True)
+class ApplyFrontierInput:
+    tenant_id: str
+    expected_app_dir: str | None = None
+    expected_db_path: str | None = None
+
+
+@activity.defn(name='capture_apply_dispatch_frontier')
+async def capture_apply_dispatch_frontier_activity(payload: ApplyFrontierInput) -> int:
+    """Start the next standing poll only after observing its own writer frontier."""
+    from jobctrl.database import get_connection
+    from jobctrl.infrastructure.apply_controls import capture_apply_dispatch_frontier
+    from jobctrl.infrastructure.temporal.run_in_activity import run_blocking_with_heartbeat
+    from jobctrl.infrastructure.temporal.runtime_guard import assert_activity_runtime
+
+    assert_activity_runtime(expected_app_dir=payload.expected_app_dir, expected_db_path=payload.expected_db_path)
+    return await run_blocking_with_heartbeat(
+        lambda: capture_apply_dispatch_frontier(get_connection(), tenant_id=payload.tenant_id)[0],
+        starting_message='capturing Apply dispatch frontier',
+    )
+
+
+@activity.defn(name="apply")
+async def apply_activity(payload: ApplyActivityInput) -> ApplyActivityOutput:
+    """Run the apply launcher in a worker thread, heart-beating so cancellation lands.
+
+    Exception policy:
+
+    - ``CancelledError`` — re-raised so Temporal marks the activity cancelled.
+    - ``LookupError`` (missing JobId or other lookup misses) — wrapped in a
+      non-retryable ``ApplicationError`` so the workflow fails fast.
+    - Any other exception — re-raised verbatim so Temporal's configured retry
+      policy can fire on transient browser / network / executor failures.
+    """
+
+    # Every invocation creates its own cancellation/resource owner before
+    # handing blocking launcher work to the activity executor.
+    from jobctrl.infrastructure.temporal.runtime_guard import assert_activity_runtime
+    from jobctrl.infrastructure.temporal.run_in_activity import run_blocking_with_heartbeat
+    from jobctrl.infrastructure.scoring.criteria_provider import (
+        read_apply_approval_required,
+        read_apply_concurrency,
+        read_min_fit_score,
+    )
+    from jobctrl.browser_capabilities import require_system_browser_capability
+    from jobctrl.apply.launcher import count_settled_email_refusals, main as apply_main
+    from jobctrl.apply.batch_outcome import ApplyBatchCleanupIncomplete, ApplyBatchWorkersCrashed
+    from jobctrl.apply.ownership import ApplyLauncherBusy, ApplyLauncherCleanupIncomplete, ApplyLauncherRun
+
+    assert_activity_runtime(
+        expected_app_dir=payload.expected_app_dir,
+        expected_db_path=payload.expected_db_path,
+    )
+    # A caller may have bypassed the CLI/API workflow builder. Re-check at the
+    # worker execution boundary before importing the apply launcher or touching
+    # a browser profile.
+    from jobctrl.runtime import is_bundled_runtime
+    bundled = is_bundled_runtime()
+    dedicated_scope = bundled
+    if not dedicated_scope:
+        require_system_browser_capability("auto-apply-browser")
+    workflow_id = activity.info().workflow_id
+    launcher_run = None if dedicated_scope else ApplyLauncherRun()
+    from jobctrl.apply.execution import ScopedApplyExecution
+    scoped_execution = ScopedApplyExecution() if dedicated_scope else None
+
+    def _run_apply() -> tuple[int, int, int | None]:
+        # ``continuous=True`` selects the launcher's run-forever poll mode,
+        # which it activates via ``limit == 0``.  Otherwise enforce a floor
+        # of one to keep ``limit < 1`` calls from no-oping.
+        effective_limit = 0 if payload.continuous else max(1, payload.limit)
+        approval_required = read_apply_approval_required(default=payload.approval_required)
+        min_score = read_min_fit_score(default=payload.min_score) if payload.auto_apply_loop else payload.min_score
+        workers = read_apply_concurrency(default=payload.workers) if payload.auto_apply_loop else payload.workers
+        options = dict(
+            limit=effective_limit, target_job_id=str(payload.job_id) if payload.job_id is not None else None,
+            tenant_id=payload.tenant_id, min_score=min_score, headless=payload.headless, model=payload.model,
+            dry_run=payload.dry_run, continuous=payload.continuous, workers=workers, poll_interval=60,
+            approval_required=approval_required, workflow_id=workflow_id,
+            standing_refusal_poll=payload.standing_refusal_poll or payload.auto_apply_loop,
+            dispatch_frontier=payload.dispatch_frontier,
+        )
+        if scoped_execution is not None:
+            applied, failed = scoped_execution.run(options)
+            owner_id = scoped_execution.identity
+        else:
+            options.pop("poll_interval")
+            applied, failed = apply_main(**options, install_signal_handlers=False, launcher_run=launcher_run)
+            owner_id = launcher_run.identity
+        settled = None
+        if failed and (payload.standing_refusal_poll or payload.auto_apply_loop):
+            try:
+                settled = count_settled_email_refusals(payload.tenant_id, owner_id)
+            except Exception:  # noqa: BLE001 — missing proof must retain the failed outcome
+                logger.warning("Could not verify settled Apply refusals; retaining failed batch status")
+        return applied, failed, settled
+
+
+    try:
+        applied, failed, settled_refusals = await run_blocking_with_heartbeat(
+            _run_apply,
+            starting_message="apply starting",
+            progress_message="apply still running",
+            poll_interval=15.0,
+            activity_name="apply",
+            job_context={
+                "job_id": str(payload.job_id) if payload.job_id is not None else "",
+                "dry_run": payload.dry_run,
+            },
+            on_cancel=scoped_execution.cancel if scoped_execution is not None else launcher_run.cancel,
+        )
+
+        status = "ok" if failed == 0 else "failed"
+        return ApplyActivityOutput(
+            status=status,
+            applied=int(applied),
+            failed=int(failed),
+            error=None,
+            worker_crashes=0,
+            settled_refusals=settled_refusals,
+        )
+    except ApplyBatchWorkersCrashed as exc:
+        return ApplyActivityOutput(
+            status="failed", applied=exc.counts.applied, failed=exc.counts.failed,
+            error="apply_worker_crashed", worker_crashes=exc.counts.worker_crashes,
+        )
+    except ApplyBatchCleanupIncomplete as exc:
+        raise ApplicationError(
+            str(exc), exc.counts.to_dict(), type="apply_launcher_cleanup_incomplete", non_retryable=True,
+        ) from exc
+    except (ApplyLauncherBusy, ApplyLauncherCleanupIncomplete) as exc:
+        code = "apply_launcher_busy" if isinstance(exc, ApplyLauncherBusy) else "apply_launcher_cleanup_incomplete"
+        raise ApplicationError(str(exc), type=code, non_retryable=True) from exc
+    except LookupError as exc:
+        # Missing JobId or other lookup misses are operator errors;
+        # do not retry — surface them immediately to the workflow.
+        raise ApplicationError(str(exc), type=type(exc).__name__, non_retryable=True) from exc
+
+
+# Re-exported for the registry; activity decorator metadata is preserved.
+__all__: list[Any] = ["apply_activity", "ApplyActivityInput", "ApplyActivityOutput"]

jobctrl-0.4.0/src/jobctrl/apply/auto_apply.py

@@ -0,0 +1,201 @@
+"""Worker reconciler for the settings-controlled standing apply loop."""
+
+from __future__ import annotations
+
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from temporalio.client import WorkflowExecutionStatus
+from temporalio.common import WorkflowIDConflictPolicy, WorkflowIDReusePolicy
+from temporalio.service import RPCError, RPCStatusCode
+
+from jobctrl.apply.workflow import ApplyWorkflow, ApplyWorkflowInput
+from jobctrl.browser_capabilities import browser_capability_status
+from jobctrl.domain.tenant import LOCAL_TENANT
+from jobctrl.infrastructure.scoring.criteria_provider import (
+    read_apply_approval_required,
+    read_apply_concurrency,
+    read_auto_apply_enabled,
+    read_daily_budget_usd,
+    read_min_fit_score,
+)
+
+AUTO_APPLY_WORKFLOW_PREFIX = "apply-auto"
+
+
+@dataclass(frozen=True)
+class AutoApplyLoopSettings:
+    enabled: bool
+    min_score: int
+    workers: int
+    approval_required: bool
+
+
+@dataclass(frozen=True)
+class AutoApplyReconcileResult:
+    workflow_id: str
+    action: str
+    enabled: bool
+
+    @property
+    def changed(self) -> bool:
+        return self.action == "started" or self.action.startswith("canceled")
+
+
+def auto_apply_workflow_id(tenant_id: str = str(LOCAL_TENANT)) -> str:
+    return f"{AUTO_APPLY_WORKFLOW_PREFIX}-{tenant_id}"
+
+
+def read_auto_apply_loop_settings(
+    path: Path | str | None = None,
+) -> AutoApplyLoopSettings:
+    return AutoApplyLoopSettings(
+        enabled=read_auto_apply_enabled(default=False),
+        min_score=read_min_fit_score(default=7),
+        workers=read_apply_concurrency(path, default=1),
+        approval_required=read_apply_approval_required(default=True),
+    )
+
+
+async def reconcile_auto_apply_loop(
+    client: Any,
+    *,
+    task_queue: str,
+    tenant_id: str = str(LOCAL_TENANT),
+    settings_path: Path | str | None = None,
+    expected_app_dir: str | None = None,
+    expected_db_path: str | None = None,
+) -> AutoApplyReconcileResult:
+    """Ensure the deterministic continuous apply workflow matches settings."""
+    settings = read_auto_apply_loop_settings(settings_path)
+    workflow_id = auto_apply_workflow_id(tenant_id)
+    running = await _is_workflow_running(client, workflow_id)
+    if settings.enabled:
+        capability = browser_capability_status("auto-apply-browser")
+        if capability.status != "ready":
+            if running:
+                await client.get_workflow_handle(workflow_id).cancel()
+                return AutoApplyReconcileResult(
+                    workflow_id, f"canceled_capability_{capability.status}", False
+                )
+            return AutoApplyReconcileResult(
+                workflow_id, f"blocked_capability_{capability.status}", False
+            )
+        if running:
+            return AutoApplyReconcileResult(workflow_id, "already_running", True)
+        if _budget_halt_active(
+            db_path=expected_db_path,
+            workflow_id=workflow_id,
+            settings_path=settings_path,
+        ):
+            return AutoApplyReconcileResult(workflow_id, "halted_budget_exceeded", True)
+        from jobctrl.database import get_connection
+        from jobctrl.infrastructure.apply_controls import capture_apply_dispatch_frontier
+        from jobctrl.infrastructure.runtime_identity import assert_expected_runtime
+
+        assert_expected_runtime(expected_app_dir=expected_app_dir, expected_db_path=expected_db_path)
+        conn = get_connection()
+        if conn.in_transaction:
+            raise RuntimeError('Apply dispatch cannot cross a caller-owned database transaction')
+        frontier, _ = capture_apply_dispatch_frontier(conn, tenant_id=tenant_id)
+        payload = ApplyWorkflowInput(
+            tenant_id=tenant_id,
+            expected_app_dir=expected_app_dir,
+            expected_db_path=expected_db_path,
+            dry_run=False,
+            min_score=settings.min_score,
+            workers=settings.workers,
+            limit=0,
+            approval_required=settings.approval_required,
+            continuous=True,
+            auto_apply_loop=True,
+            dispatch_frontier=frontier,
+        )
+        await client.start_workflow(
+            ApplyWorkflow.run,
+            payload,
+            id=workflow_id,
+            task_queue=task_queue,
+            id_conflict_policy=WorkflowIDConflictPolicy.USE_EXISTING,
+            id_reuse_policy=WorkflowIDReusePolicy.ALLOW_DUPLICATE,
+        )
+        return AutoApplyReconcileResult(workflow_id, "started", True)
+
+    if running:
+        await client.get_workflow_handle(workflow_id).cancel()
+        return AutoApplyReconcileResult(workflow_id, "canceled", False)
+    return AutoApplyReconcileResult(workflow_id, "already_stopped", False)
+
+
+async def _is_workflow_running(client: Any, workflow_id: str) -> bool:
+    try:
+        description = await client.get_workflow_handle(workflow_id).describe()
+    except RPCError as exc:
+        if exc.status == RPCStatusCode.NOT_FOUND:
+            return False
+        raise
+    status = getattr(description, "status", None)
+    return status == WorkflowExecutionStatus.RUNNING or getattr(status, "name", "") == "CONTINUED_AS_NEW"
+
+
+def _budget_halt_active(
+    *,
+    db_path: str | None,
+    workflow_id: str,
+    settings_path: Path | str | None,
+) -> bool:
+    if not db_path:
+        return False
+    path = Path(db_path)
+    if not path.exists():
+        return False
+    from jobctrl.database import _refuse_unresolved_initialization
+
+    _refuse_unresolved_initialization(path)
+    try:
+        with sqlite3.connect(path) as conn:
+            row = conn.execute(
+                """
+                SELECT status, error_code
+                FROM workflow_run_projections
+                WHERE workflow_id = ?
+                LIMIT 1
+                """,
+                (workflow_id,),
+            ).fetchone()
+            if not row or str(row[0]) != "failed" or str(row[1]) != "budget_exceeded":
+                return False
+            daily_budget = read_daily_budget_usd(settings_path, default=25.0)
+            spend_day = datetime.now(timezone.utc).date().isoformat()
+            spend = conn.execute(
+                "SELECT COALESCE(SUM(estimated_usd), 0) FROM llm_spend WHERE day = ?",
+                (spend_day,),
+            ).fetchone()
+            apply_spend = conn.execute(
+                "SELECT input_tokens + output_tokens FROM llm_spend WHERE day = ? AND lane = 'apply'",
+                (spend_day,),
+            ).fetchone()
+    except sqlite3.Error:
+        return False
+    estimated = float(spend[0] or 0.0) if spend else 0.0
+    from jobctrl.infrastructure.scoring.criteria_provider import read_lane_token_limits
+
+    apply_limit = read_lane_token_limits(settings_path)["apply"]
+    apply_tokens = int(apply_spend[0] or 0) if apply_spend else 0
+    return (
+        (daily_budget > 0 and estimated >= daily_budget)
+        or (apply_limit > 0 and apply_tokens >= apply_limit)
+    )
+
+
+__all__ = [
+    "AUTO_APPLY_WORKFLOW_PREFIX",
+    "AutoApplyLoopSettings",
+    "AutoApplyReconcileResult",
+    "auto_apply_workflow_id",
+    "read_auto_apply_loop_settings",
+    "reconcile_auto_apply_loop",
+]