cli-agent-runner 0.3.11__tar.gz → 0.3.12__tar.gz

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/.vulture-whitelist.py

@@ -6,6 +6,12 @@
 # bare name below marks one field "used". SSOT = the @dataclass definitions in
 # agent_runner/; a new field is covered by regenerating, never by editing here.
 
+# agent_runner._bounded.BoundedResult
+rc
+stdout
+stderr
+timed_out
+
 # agent_runner._monitor_state.LocalSource
 log_dir
 
@@ -161,6 +167,11 @@ monitor
 phases
 plugins
 schedule
+goal
+
+# agent_runner.config.models.GoalConfig
+ledger
+checks
 
 # agent_runner.config.models.MonitorConfig
 auth_fail_patterns
@@ -232,6 +243,12 @@ pause_windows
 stash_idempotency_s
 dirty_action
 
+# agent_runner.config.models._GoalCheckConfig
+name
+cmd
+cwd
+timeout_s
+
 # agent_runner.config.models._HostHealthBrakeConfig
 memory_high
 memory_high_step_pct
@@ -281,6 +298,11 @@ codifies
 guarded_by
 current_state
 
+# agent_runner.goal.Advisory
+observation
+question
+confidence
+
 # agent_runner.hooks.HookContext
 work_dir
 log_dir

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.12] - 2026-09-18
+
+### Added
+- `[goal]` config table: a markdown lessons `ledger` (listed in `[prompt] files` at index >= 1, and — since it must survive the round's own `git stash` — required to sit under `log_dir` or outside `work_dir`) plus `[[goal.checks]]` (`name`, `cmd` argv, optional `timeout_s`) — objective, CLI-agnostic checks the round child runs after each round's agent exits, each emitting a `goal_check` event (`satisfied` bool, optional `value`).
+- Treadmill assessor (advisory-only): across the last 3 completed rounds, if every round showed activity but at least one goal check stayed unsatisfied with an unchanged signature, serve writes one edge-triggered advisory to the ledger and emits a `goal_assessment` event (never on convergence). The ledger's `[prompt] files` membership carries it into the next round's prompt.
+- Advisory/kill firewall: the goal loop never CAUSES a kill or give-up — the kill/give-up path reads events by kind and stays blind to `goal_check`/`goal_assessment`. A goal check's own wall time does count toward the round's duration, so a long check can DELAY (never trigger) the fast-spin `stalled_no_progress`/`crash_loop` breakers; config load warns if the total check budget reaches that window.
+
+Check timeouts fold into the round's own timeout budget. No config migration required (v0.3.11 silently ignores an unrecognized `[goal]` table). `peek --json` schema stays `2.6`.
+
 ## [0.3.11] - 2026-09-17
 
 ### Added

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.11
+Version: 0.3.12
 Summary: Restart-on-exit supervisor for autonomous CLI agents
 Project-URL: Homepage, https://github.com/wan9yu/cli-agent-runner
 Project-URL: Documentation, https://github.com/wan9yu/cli-agent-runner#readme

cli_agent_runner-0.3.12/agent_runner/_bounded.py

@@ -0,0 +1,135 @@
+"""Sanctioned timeout-bounded subprocess primitive.
+
+Runs a command in its OWN session under a wall-clock timeout, escalating
+TERM -> grace -> killpg(SIGKILL) on breach so a hung process leaves no
+descendants (a backgrounded grandchild included, since killpg targets the
+whole process group). Returns a ``BoundedResult`` with ``timed_out=True`` on
+breach instead of raising -- the caller decides how to react. No ``clock``
+parameter: ``subprocess.communicate(timeout=)`` self-times, there is no raw
+wall-clock read here to abstract.
+
+Two hardening properties beyond the plain TERM/KILL escalation:
+
+- **Bounded even against a session-detached pipe holder.** A descendant that
+  ``setsid``-detaches out of the killed process group can still hold the
+  inherited stdout/stderr pipe open, so the final drain after ``killpg`` would
+  block forever waiting on EOF. Every drain is capped at ``_KILL_GRACE_S``; on
+  breach the read ends are closed and whatever was captured so far is returned.
+  The whole primitive therefore returns within ``timeout_s + 2*_KILL_GRACE_S``
+  (one grace for TERM->KILL, one for the post-kill drain) no matter what the
+  command spawns. A truly detached grandchild in its OWN session is NOT reaped
+  -- killpg cannot reach it; keep checks in a single process group.
+- **Reap-on-interrupt.** A SIGTERM to the supervisor (see
+  ``cli.common.install_term_handler``, which raises ``KeyboardInterrupt``)
+  propagates out of ``communicate()`` while the command runs in its own
+  session and would otherwise never be signalled. Any ``BaseException`` out of
+  a wait therefore SIGKILLs the whole group, closes the pipes, and reaps under
+  one bounded ``_KILL_GRACE_S`` wait before re-raising, mirroring
+  ``agent_runtime._kill_pgroup``'s bounded-wait-after-SIGKILL.
+
+Kept out of the startup import graph on purpose (see
+tests/invariants/test_import_footprint.py): callers import it function-scope.
+"""
+
+from __future__ import annotations
+
+import os
+import signal
+import subprocess  # noqa: TID251 — agent_runner._bounded is the sanctioned timeout-bounded subprocess primitive
+from dataclasses import dataclass
+from pathlib import Path
+
+_KILL_GRACE_S = 3  # grace between TERM and killpg(SIGKILL), and for the post-kill drain
+
+
+@dataclass(frozen=True)
+class BoundedResult:
+    rc: int
+    stdout: str
+    stderr: str
+    timed_out: bool
+
+
+def _kill_group(proc: subprocess.Popen) -> None:
+    try:
+        os.killpg(proc.pid, signal.SIGKILL)
+    except OSError:
+        pass
+
+
+def _close_pipes(proc: subprocess.Popen) -> None:
+    for pipe in (proc.stdout, proc.stderr):
+        if pipe is not None:
+            try:
+                pipe.close()
+            except OSError:
+                pass
+
+
+def _drain_after_kill(proc: subprocess.Popen, exc: subprocess.TimeoutExpired) -> tuple[str, str]:
+    """Best-effort drain after ``killpg(SIGKILL)`` that never blocks unbounded.
+
+    A ``setsid``-detached descendant can still hold the stdout/stderr pipe open,
+    so stop waiting on it: close the read ends and reap the (already-SIGKILLed)
+    immediate child under one more ``_KILL_GRACE_S`` cap. ``TimeoutExpired.output``
+    is ``bytes`` even on this text-mode Popen (the partial read captured at
+    timeout bypasses the text-decoding wrapper), so decode it here with the
+    same ``errors="replace"`` policy; fall back to empty strings if the
+    attribute isn't bytes at all."""
+    _close_pipes(proc)
+    try:
+        proc.wait(timeout=_KILL_GRACE_S)
+    except subprocess.TimeoutExpired:
+        pass
+    out = (
+        exc.output.decode("utf-8", errors="replace")
+        if isinstance(exc.output, (bytes, bytearray))
+        else ""
+    )
+    err = (
+        exc.stderr.decode("utf-8", errors="replace")
+        if isinstance(exc.stderr, (bytes, bytearray))
+        else ""
+    )
+    return out, err
+
+
+def run_bounded(argv: list[str], *, cwd: Path, timeout_s: int) -> BoundedResult:
+    """Run argv in its own session under a wall-clock timeout, escalating
+    TERM -> grace -> killpg on breach so a hung command leaves no reachable
+    descendants. Returns timed_out=True on breach -- never raises on breach.
+    A ``BaseException`` out of a wait (e.g. a SIGTERM-driven KeyboardInterrupt)
+    SIGKILLs the group, closes the pipes, and reaps under one bounded
+    ``_KILL_GRACE_S`` wait, then re-raises, so an interrupted check is torn
+    down (not left a zombie) rather than orphaned. ``errors="replace"`` keeps a
+    non-UTF-8 byte in the command's output from raising a UnicodeDecodeError
+    past the caller's fail-open guard."""
+    proc = subprocess.Popen(
+        argv,
+        cwd=cwd,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        errors="replace",
+        start_new_session=True,
+    )
+    try:
+        try:
+            out, err = proc.communicate(timeout=timeout_s)
+            return BoundedResult(rc=proc.returncode, stdout=out, stderr=err, timed_out=False)
+        except subprocess.TimeoutExpired:
+            proc.terminate()
+            try:
+                out, err = proc.communicate(timeout=_KILL_GRACE_S)
+            except subprocess.TimeoutExpired as exc:
+                _kill_group(proc)
+                out, err = _drain_after_kill(proc, exc)
+            return BoundedResult(rc=proc.returncode, stdout=out, stderr=err, timed_out=True)
+    except BaseException:
+        _kill_group(proc)
+        _close_pipes(proc)
+        try:
+            proc.wait(timeout=_KILL_GRACE_S)
+        except subprocess.TimeoutExpired:
+            pass
+        raise

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/_docgen.py

@@ -21,6 +21,7 @@ from agent_runner.cli.init_cmd import _preset_names
 from agent_runner.config import (
     AgentConfig,
     Config,
+    GoalConfig,
     MonitorConfig,
     MonitorHostHealthConfig,
     PhasesConfig,
@@ -29,6 +30,7 @@ from agent_runner.config import (
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _GoalCheckConfig,
     _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
@@ -72,6 +74,7 @@ _SECTIONS: list[tuple[str, type, list[tuple[str, type]]]] = [
     ("phases", PhasesConfig, []),
     ("plugins", PluginsConfig, []),
     ("schedule", ScheduleConfig, []),
+    ("goal", GoalConfig, [("goal.checks", _GoalCheckConfig)]),
 ]
 
 
@@ -102,13 +105,23 @@ def _field_table(dc: type) -> list[str]:
     return rows
 
 
+# Nested sub-sections that are TOML arrays-of-tables (`[[name]]`), not single
+# sub-tables (`[name]`): the parent field is a list/tuple of the sub-dataclass,
+# so the header must double-bracket or a copy-pasted single `[goal.checks]` is
+# rejected by the parser (_parse_goal expects a list).
+_ARRAY_OF_TABLES_SECTIONS = frozenset({"goal.checks"})
+
+
 def render_config_schema_table() -> str:
     """Markdown sub-sections per Config dataclass with field/type/default."""
     parts: list[str] = []
     for name, dc, nested in _SECTIONS:
         parts += [f"### `[{name}]`", "", *_field_table(dc), ""]
         for sub_name, sub_dc in nested:
-            parts += [f"#### `[{sub_name}]`", "", *_field_table(sub_dc), ""]
+            brackets = (
+                f"[[{sub_name}]]" if sub_name in _ARRAY_OF_TABLES_SECTIONS else f"[{sub_name}]"
+            )
+            parts += [f"#### `{brackets}`", "", *_field_table(sub_dc), ""]
     return "\n".join(parts).rstrip()
 
 

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/_lifecycle.py

@@ -56,7 +56,7 @@ def outer_round_ceiling_s(cfg: Config, phase_arg: str | None) -> int:
             (cfg.profile_for(p).runtime.round_budget_s for p in (cfg.phases.list or [])),
             default=cfg.runtime.round_budget_s,
         )
-    _, outer_ceiling = timeout_budget(inner)
+    _, outer_ceiling = timeout_budget(inner, goal_checks_allowance_s=cfg.goal_checks_allowance_s)
     return outer_ceiling
 
 

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/_serve_policy.py

@@ -303,17 +303,18 @@ _STOP_GRACE_MARGIN_S = 10  # pad above _ROUND_TERM_GRACE_S for systemd stop-requ
 _ROUND_UNREAPED_RC = 137  # 128 + SIGKILL(9): reads as a kill in the crash-loop path
 
 
-def timeout_budget(round_budget_s: int) -> tuple[int, int]:
+def timeout_budget(round_budget_s: int, *, goal_checks_allowance_s: int = 0) -> tuple[int, int]:
     """Single source for the round-timeout safety budget.
 
     Returns ``(timeout_stop_sec, outer_ceiling_s)``:
 
     - ``outer_ceiling_s`` — the in-process outer wall-clock ceiling for the
       round subprocess (``api.outer_round_ceiling_s``): ``round_budget_s``
-      plus reap grace + git-commit ceiling + hook allowance, so it only trips
-      when the round supervisor itself is wedged, never during its own
-      bounded post-round cleanup. The reap margin must cover the widest grace
-      ANY round can be configured with -- a cooperative agent's
+      plus reap grace + git-commit ceiling + hook allowance + the goal-check
+      executor's own allowance, so it only trips when the round supervisor
+      itself is wedged, never during its own bounded post-round cleanup (nor
+      a slow-but-still-bounded goal check). The reap margin must cover the
+      widest grace ANY round can be configured with -- a cooperative agent's
       ``sigterm_grace_s`` is boot-capped at ``_ROUND_TERM_GRACE_S``
       (``config/models.py``'s mirror of this module's single source), not
       the non-cooperative default ``_REAP_GRACE_S``, so the margin is
@@ -324,12 +325,19 @@ def timeout_budget(round_budget_s: int) -> tuple[int, int]:
       SIGTERM to reach and drain the round (``_ROUND_TERM_GRACE_S``) plus a
       stop-request overhead pad, so `systemctl stop` never SIGKILLs a round
       that is draining normally.
+
+    ``goal_checks_allowance_s`` (default 0, byte-identical to the old
+    signature when omitted) is the caller's ``GoalConfig.checks_allowance_s``
+    when ``[goal]`` is configured -- folded into this ONE ceiling rather than
+    a second, separate one, so the goal-check path can never itself trip
+    ``round_supervisor_wedged``.
     """
     outer_ceiling_s = (
         round_budget_s
         + max(_REAP_GRACE_S, _ROUND_TERM_GRACE_S)
         + _GIT_COMMIT_TIMEOUT_S
         + _HOOK_ALLOWANCE_S
+        + goal_checks_allowance_s
     )
     timeout_stop_sec = outer_ceiling_s + _ROUND_TERM_GRACE_S + _STOP_GRACE_MARGIN_S
     return timeout_stop_sec, outer_ceiling_s

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.11'
-__version_tuple__ = version_tuple = (0, 3, 11)
+__version__ = version = '0.3.12'
+__version_tuple__ = version_tuple = (0, 3, 12)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/config/__init__.py

@@ -40,6 +40,7 @@ from agent_runner.config.models import (  # noqa: F401 — public re-export
     _VCS_ALLOWED_FIELDS,
     AgentConfig,
     Config,
+    GoalConfig,
     MonitorConfig,
     MonitorHostHealthConfig,
     PhaseOverride,
@@ -50,17 +51,22 @@ from agent_runner.config.models import (  # noqa: F401 — public re-export
     RuntimeConfig,
     ScheduleConfig,
     VcsConfig,
+    _GoalCheckConfig,
     _HostHealthBrakeConfig,
     _HostHealthDiskConfig,
     _HostHealthMemoryConfig,
     _HostHealthPressureConfig,
 )
-from agent_runner.config.validators import _reject_control_chars  # noqa: F401
+from agent_runner.config.validators import (  # noqa: F401 — public re-export
+    _reject_control_chars,
+    _resolve_against_work_dir,
+)
 
 __all__ = [
     "AgentConfig",
     "Config",
     "ConfigError",
+    "GoalConfig",
     "MonitorConfig",
     "MonitorHostHealthConfig",
     "PhaseOverride",

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/config/loader.py

@@ -7,12 +7,14 @@ Thin glue by design — every table's own validation lives in ``parsers.py``.
 from __future__ import annotations
 
 import tomllib
+import warnings
 from pathlib import Path
 
 from agent_runner.config.errors import ConfigError
 from agent_runner.config.models import Config, PhasesConfig
 from agent_runner.config.parsers import (
     _parse_agent,
+    _parse_goal,
     _parse_monitor,
     _parse_phase_overrides,
     _parse_plugins,
@@ -56,6 +58,102 @@ def _reject_static_resume_flag(cfg) -> None:
             )
 
 
+def _reject_goal_ledger_not_listed(cfg: Config) -> None:
+    """A [goal].ledger doesn't exist at cold start -- it's written by the agent
+    mid-run -- so it must ride in [prompt] files at index >= 1: index 0 is a
+    fatal-on-missing read (prompt_loader.py), and the single `file=` form can
+    never carry a second entry at all. Checks every configured phase's own
+    effective files list, mirroring Config.profile_for's override-or-base
+    resolution rule for prompt_files (no override -> the base [prompt] table)."""
+    if cfg.goal is None:
+        return
+    ledger = cfg.goal.ledger
+    phase_names: list[str | None] = list(cfg.phases.list) if cfg.phases.list else [None]
+    for phase_name in phase_names:
+        where = "[prompt]" if phase_name is None else f"[phases.{phase_name}.prompt]"
+        prompt_files = cfg.profile_for(phase_name).prompt_files
+        # No override -> [] via cfg.prompt.files, which is already [] when the
+        # single `file=` form is in play (parser-enforced): never carries a
+        # second entry.
+        files = (
+            [str(p) for p in prompt_files]
+            if prompt_files is not None
+            else [str(p) for p in cfg.prompt.files]
+        )
+        if ledger not in files or files.index(ledger) == 0:
+            raise ConfigError(
+                f"{where}: [goal] ledger {ledger!r} is not listed in the resolved "
+                "prompt files at index >= 1 (the single `file=` form can't carry it, "
+                f"and index 0 doesn't exist at cold start); list {ledger!r} in "
+                "[prompt] files at index >= 1"
+            )
+
+
+def _reject_goal_ledger_in_stash_swept_tree(cfg: Config) -> None:
+    """The ``[goal].ledger`` is supervisor-written and must PERSIST across
+    rounds, but the round's own vcs step sweeps the work tree: under the
+    DEFAULT ``[vcs] dirty_action="stash"`` a ``git stash push -u`` stashes
+    every dirty path EXCEPT ``log_dir`` (see ``vcs_state``'s exclude pathspec).
+    A ledger resolved INSIDE ``work_dir`` but OUTSIDE ``log_dir`` would be
+    stashed away as orphan work right after the round it fired for -- the steer
+    would silently last one round.
+
+    Pure path arithmetic (no git): require the resolved ledger to sit OUTSIDE
+    ``work_dir``, OR UNDER ``log_dir`` (the one work-tree path the stash
+    pathspec excludes). Composes with -- and runs after --
+    ``_reject_goal_ledger_not_listed``."""
+    if cfg.goal is None:
+        return
+    # .resolve() all three: an absolute log_dir (or ledger) is NOT canonicalized
+    # by _expand_and_resolve (only a relative path is), so a symlinked absolute
+    # log_dir (e.g. /tmp -> /private/tmp on macOS) would otherwise FALSE-REJECT
+    # a ledger genuinely under it -- work_dir is always canonical already
+    # (loader.load_config resolves it unconditionally), so this is a no-op there.
+    ledger = Path(cfg.goal.ledger).resolve()
+    work_dir = cfg.runtime.work_dir.resolve()
+    log_dir = cfg.runtime.log_dir.resolve()
+    if ledger.is_relative_to(work_dir) and not ledger.is_relative_to(log_dir):
+        raise ConfigError(
+            f"[goal] ledger {cfg.goal.ledger!r} resolves inside runtime.work_dir "
+            f"({work_dir}) but outside runtime.log_dir ({log_dir}): the default "
+            '[vcs] dirty_action="stash" would stash it away as orphan work after '
+            "the round it fired for, so the steer would last only one round. Put "
+            'the ledger under log_dir (e.g. ledger = "logs/lessons.md") or at an '
+            "absolute path outside work_dir."
+        )
+
+
+def _warn_goal_checks_budget_disarms_fast_spin(cfg: Config) -> None:
+    """A goal check's wall time counts inside ``round_duration_s``, the
+    discriminator for serve's fast-spin give-up breakers (``crash_loop`` counts
+    a crash only under ``CRASH_LOOP_SHORT_EXIT_S``, ``stalled_no_progress`` only
+    under ``_NO_PROGRESS_SHORT_S``). A goal-check budget at or above that short
+    window can push an otherwise fast-crashing round past the threshold and
+    DISARM the breaker. The goal loop still never CAUSES a give-up -- the
+    firewall keeps the kill/give-up path blind to ``goal_*`` events -- so this
+    is the one place a long check can only DELAY (never trigger) one. A
+    legitimate ``pytest`` goal-check may well exceed the window, so this WARNS
+    (via the same load-time ``warnings`` channel plugin-load failures use)
+    rather than rejecting."""
+    if cfg.goal is None:
+        return
+    # Function-scope import: config/ must not import _serve_policy at module
+    # scope (_serve_policy imports agent_runner.config for ConfigError -- a
+    # cycle). By load_config-call time the module is importable.
+    from agent_runner._serve_policy import _NO_PROGRESS_SHORT_S
+
+    allowance = cfg.goal.checks_allowance_s
+    if allowance >= _NO_PROGRESS_SHORT_S:
+        warnings.warn(
+            f"[goal] total goal-check budget is {allowance}s, at or above the "
+            f"{_NO_PROGRESS_SHORT_S}s fast-spin give-up window: a goal check's wall "
+            "time counts toward the round's own duration, so a long check can delay "
+            "(never trigger) the stalled_no_progress/crash_loop breakers. Keep total "
+            "check time under that window if you rely on them.",
+            stacklevel=2,
+        )
+
+
 def _check_schema_version(raw: dict) -> None:
     """Boot gate: a config's ``schema_version`` decouples the on-disk config
     shape from the installed package version, so a config can be migrated
@@ -136,6 +234,11 @@ def load_config(toml_path: Path) -> Config:
     monitor = _parse_monitor(_require_table(raw, "monitor"))
     plugins = _parse_plugins(_require_table(raw, "plugins"))
     schedule_cfg = _parse_schedule(_require_table(raw, "schedule"))
+    goal = (
+        _parse_goal(_require_table(raw, "goal"), project_name=project_name, work_dir=work_dir)
+        if "goal" in raw
+        else None
+    )
 
     cfg = Config(
         agent=agent,
@@ -146,6 +249,7 @@ def load_config(toml_path: Path) -> Config:
         phases=phases_cfg,
         plugins=plugins,
         schedule=schedule_cfg,
+        goal=goal,
     )
 
     # Verify + import discovered agent_runner.plugins entry points now that
@@ -158,5 +262,8 @@ def load_config(toml_path: Path) -> Config:
         apply_plugin_disable(plugins.disable)
 
     _reject_static_resume_flag(cfg)
+    _reject_goal_ledger_not_listed(cfg)
+    _reject_goal_ledger_in_stash_swept_tree(cfg)
+    _warn_goal_checks_budget_disarms_fast_spin(cfg)
 
     return cfg

{cli_agent_runner-0.3.11 → cli_agent_runner-0.3.12}/agent_runner/config/models.py

@@ -32,6 +32,15 @@ DEFAULT_TERMINAL_MARKER = '"type":"result"'
 # agent's preset gets from the round leader (see AgentConfig.sigterm_grace_s).
 DEFAULT_SIGTERM_GRACE_S = 10
 
+# Default [[goal.checks]] timeout_s: an objective goal-check is a lightweight
+# scriptable sanity command (e.g. a lint/test run), not another agent round.
+DEFAULT_GOAL_CHECK_TIMEOUT_S = 10
+
+# Boot cap for [[goal.checks]] timeout_s: a value above this is rejected
+# outright, not clamped, so one slow check can't silently eat the round's
+# own time budget.
+_MAX_GOAL_CHECK_TIMEOUT_S = 30
+
 # Ceiling for [agent] sigterm_grace_s: sits a STRICT ~3s BELOW _serve_policy's
 # _ROUND_TERM_GRACE_S (15, the supervisor's own wait for the round leader) --
 # NOT equal to it. The margin buys the round LEADER's own cooperative
@@ -306,6 +315,56 @@ class ScheduleConfig:
         return bool(self.run_windows or self.pause_windows)
 
 
+@dataclass(frozen=True)
+class _GoalCheckConfig:
+    """One ``[[goal.checks]]`` entry: an objective, scriptable check (e.g. a
+    lint or test run) the operator trusts over the agent's own self-report.
+    ``cwd`` is a raw operator string, resolved by the check runner, not here."""
+
+    name: str
+    cmd: list[str]
+    cwd: str | None = None
+    timeout_s: int = DEFAULT_GOAL_CHECK_TIMEOUT_S
+
+
+@dataclass(frozen=True)
+class GoalConfig:
+    """The ``[goal]`` table: objective goal-checks plus the lessons-ledger
+    path threaded into the prompt across rounds. ``Config.goal`` stays
+    ``None`` when ``[goal]`` is absent -- the steering loop is opt-in.
+
+    ``ledger`` is required; ``checks`` defaults to an empty tuple (a ledger-only
+    ``[goal]`` runs the treadmill assessor with nothing objective to converge
+    on -- valid, if degenerate), so it is declared last with a default to match
+    the parser's ``goal.checks`` default."""
+
+    ledger: str
+    checks: tuple[_GoalCheckConfig, ...] = ()
+
+    @property
+    def checks_allowance_s(self) -> int:
+        """Worst-case wall-clock the goal-check executor can consume in one
+        round, so the round-timeout budget (``_serve_policy.timeout_budget``)
+        can fold it into the single outer ceiling -- a slow (or hung) check
+        must never trip ``round_supervisor_wedged`` itself.
+
+        The executor runs every check SEQUENTIALLY with no short-circuit on
+        failure/timeout, and each breach costs TWO ``_KILL_GRACE_S`` windows,
+        not one: ``run_bounded`` spends up to ``timeout_s + 2*_KILL_GRACE_S``
+        on a breach (one grace for TERM->killpg, one for the bounded post-kill
+        drain that never blocks on a session-detached pipe holder). So the
+        all-hang worst case is every check's own timeout PLUS two kill graces
+        EACH.
+
+        Local import: this module sits on the frozen startup graph
+        (``test_import_footprint.py``), and ``_bounded`` does not -- a
+        module-scope import here would pull it onto that graph.
+        """
+        from agent_runner._bounded import _KILL_GRACE_S
+
+        return sum(c.timeout_s for c in self.checks) + len(self.checks) * 2 * _KILL_GRACE_S
+
+
 @dataclass(frozen=True)
 class Profile:
     """Fully-resolved per-phase execution profile.
@@ -333,6 +392,14 @@ class Config:
     phases: PhasesConfig = field(default_factory=PhasesConfig)
     plugins: PluginsConfig = field(default_factory=PluginsConfig)
     schedule: ScheduleConfig = field(default_factory=ScheduleConfig)
+    goal: GoalConfig | None = None
+
+    @property
+    def goal_checks_allowance_s(self) -> int:
+        """``goal.checks_allowance_s``, or 0 when ``[goal]`` is absent -- the
+        one-liner both ``_lifecycle.outer_round_ceiling_s`` and
+        ``service_unit``'s ``TimeoutStopSec`` derivation need, deduped here."""
+        return self.goal.checks_allowance_s if self.goal is not None else 0
 
     def profile_for(self, phase: str | None) -> Profile:
         """Resolve the effective execution profile for a phase.
@@ -429,3 +496,7 @@ _PROMPT_ALLOWED_FIELDS = frozenset(
 
 # Keys allowed under a [schedule] table (top-level or per-phase).
 _SCHEDULE_ALLOWED_FIELDS = frozenset({"timezone", "run_windows", "pause_windows"})
+
+# Keys allowed under the [goal] table and each [[goal.checks]] entry.
+_GOAL_ALLOWED_FIELDS = frozenset(f.name for f in dataclasses.fields(GoalConfig))
+_GOAL_CHECK_ALLOWED_FIELDS = frozenset(f.name for f in dataclasses.fields(_GoalCheckConfig))