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

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

@@ -17,6 +17,7 @@ buffer
 name
 post_round_hooks
 cooperative_stop
+resume_flag
 
 # agent_runner._round_outcome.RoundOutcome
 mem_terminated
@@ -239,6 +240,9 @@ warning_consecutive_samples
 # agent_runner.config.models._HostHealthDiskConfig
 warning_pct
 critical_pct
+growth_window_s
+disk_growth_pct_per_hr_warning
+inode_growth_pct_per_hr_warning
 
 # agent_runner.config.models._HostHealthMemoryConfig
 avail_min_mb

cli_agent_runner-0.3.11/BACKLOG.md

@@ -0,0 +1,195 @@
+# Backlog
+
+Known follow-ups and candidate work — real design or behavior decisions, not
+defects. Each entry carries enough context to act on without re-deriving it.
+
+Items marked **NEEDS_DESIGN** change user-visible behavior and are held for an
+explicit decision — they are not shipped silently in a maintenance release.
+
+**Ordered by priority** (highest first). The number is a rank, not a stable id.
+Priority follows the sharpest differentiator: prove and deepen host-health /
+cooperative pre-OOM supervision on constrained hosts first (items 1–2); the
+cognitive / goal-adherence layer (item 3) builds on that same control loop;
+cross-CLI resume breadth and reach are lower.
+
+## 1. Prove cooperative pre-OOM drain end-to-end on a constrained cgroup — NEEDS_DESIGN
+
+The host-health mechanisms built across the 0.3.x line — the cgroup
+memory-growth-rate detector (0.3.1), the `memory.high` soft-brake (0.3.7), and
+the typed `cooperative_stop` signal (0.3.9) — have never been demonstrated
+*together*, end-to-end, under real memory pressure on a small (~462 MB) cgroup.
+The load-bearing property is: the agent is cooperatively drained **before** the
+kernel OOM killer fires. It is provable with a synthetic memory-growing child
+under a constrained cgroup — no live model needed. Build that harness, verify
+the full detect → brake → drain loop, and pin the small-host calibration
+(swap-floor + PSI thresholds) and reap-safety (PID-reuse, orphan reap) as a
+durable, tested execution guarantee. Making this claim demonstrable is the
+highest-value work on the list; everything below is secondary to it.
+
+## 2. Runaway session-footprint host-health signal — NEEDS_DESIGN
+
+A resumed CLI session file (e.g. pi's session `.jsonl`) grows unbounded across
+rounds — a disk / inode pressure surface only the supervisor can see, and one
+that cross-round resume (0.3.10) amplifies. Add a host disk/inode pressure
+detector as a leading indicator so the pre-OOM brake can fire earlier and more
+specifically. Frame it as a *host* signal (any growing per-agent footprint),
+not a single-CLI feature.
+
+## 3. Cognitive / goal-adherence supervision loop (observe → assess → steer → persist) — NEEDS_DESIGN
+
+Today the supervisor watches *resource* health (memory / host) and *mechanical*
+progress (no-usage, substrate fingerprint, repetitive-tool). It cannot tell when
+an agent is "on a treadmill" — busy (produces output, edits files, exits 0) but
+not actually advancing toward its goal. Add a second, **advisory** layer to the
+same round-loop: a plugin observes each round, assesses progress toward a
+declared goal, and — only when warranted — injects a short, grounded advisory
+into the *next* round's context (through the existing `inject_context` path) that
+the agent may heed or dismiss.
+
+Design spine (composes as a fold over the durable event bus + `inject_context`,
+**not** a new live callback — the round is a fresh subprocess, so cross-round
+state is file/event-based; this re-adds a feedback seam an earlier release
+removed for lack of a producer, but strictly narrower: a data-return / fold, not
+arbitrary context mutation):
+
+- A first-class `[goal]` config (the "goal command"). PRIMARY verification is
+  **objective**: operator-declared `goal.checks` (a command the supervisor runs
+  each round — exit 0 = satisfied, an optional numeric target) and milestones,
+  run through the reap-safe / timeout / killpg machinery so a check can never
+  orphan or blow the cgroup. An optional, objective-gated LLM assessor is a last
+  resort, never in the base install.
+- A zero-cost default assessor: an objective **"treadmill signature"**
+  (activity-high + net-convergence-low, from signals already emitted; requires
+  persistence over K rounds + affirmative evidence, so false positives stay near
+  zero).
+- **Hard invariant — the advisory / kill firewall:** the advisory path is
+  strictly separate from the give-up / kill decision. A possibly-wrong assessor
+  can steer but can NEVER influence a kill (a distinct event kind the kill path
+  never reads, plus an import firewall; the assessment type structurally has no
+  kill field). Killing stays on the conservative mechanical path.
+- Steering is advisory only: a fixed schema that cannot express a command
+  (grounded observation + a question + confidence + a respected one-line
+  dismissal), edge-triggered, one concern at a time, dismiss-and-respect so it
+  never nags.
+- CLI-agnostic: reads the agent's merged log + the goal; works around any CLI.
+- Persistence rides a supervisor-owned, bounded, append-only lessons ledger
+  re-injected each round (subordinate to the disk host-health signal in item 2).
+  The supervisor never edits the agent's own memory files — it may *suggest* the
+  agent record a lesson.
+
+Sequence this after items 1–2: it is a second consumer of the same
+observe → assess → act control loop (mechanical actuator kills, advisory
+actuator steers), and it earns its slot only once the resource edge is proven.
+
+## 4. SECURITY containment guidance
+
+agent-runner is lifecycle-safety + observability, not containment — a
+deliberate boundary that is currently undocumented, so it reads as a gap. Add a
+SECURITY section that states the division plainly and gives the operator
+concrete containment guidance: a dedicated unprivileged user, a container/VM via
+`exec_prefix`, egress limits, no passwordless sudo, read-only mounts. Docs-only.
+
+## 5. claude cross-round resume — NEEDS_DESIGN
+
+0.3.10 shipped resume for pi only (its `--session-id` is idempotent —
+create-or-resume). claude's `--session-id` is create-only and `--resume` is a
+separate flag, so it needs a create-vs-resume state machine gated on the prior
+round's outcome (a crashed round re-creates rather than `--resume`-errors), plus
+an empirical check that `claude -p --resume <id>` with the prompt on stdin
+actually resumes **and** runs the new turn (rather than silently no-opping).
+Keep it a thin per-CLI declaration; if it forces heavy session-state ownership,
+that is the signal it belongs at the CLI layer, not here.
+
+## 6. Surface resume in the preflight (doctor / peek) — NEEDS_DESIGN
+
+resume is the one manifest-declared capability not shown by `doctor` / `peek`
+(unlike `cooperative_stop` and the SIGTERM grace). An operator on a
+resume-capable preset has no preflight way to confirm resume will engage for
+their phase config — in particular the deliberate cold-start on an ambiguous
+phase is silent until they notice no `session_resumed` events. Add a preflight
+line (with a "resume will not engage — ambiguous phase" note). Requires a `peek`
+schema bump.
+
+## 7. Resume for gemini / codex / kimi — NEEDS_DESIGN
+
+Each has a different resume shape (gemini resumes by index/latest, not a chosen
+id; codex uses a subcommand plus a captured id). Extending resume means widening
+the manifest `resume_flag` into a small sum type with a per-variant injection at
+the argv-build site — never optional fields bolted onto one struct. Ship only
+the variants whose resume is verified to work end-to-end.
+
+## 8. Fleet fan-in view — NEEDS_DESIGN
+
+Aggregate several supervised hosts into one place to watch, built on the
+existing remote-relay primitives — the density story (many cheap / constrained
+boxes under one supervisor). A larger effort; sequence it after the pre-OOM edge
+(item 1) is proven, so it fans in verified hosts rather than claimed ones.
+
+## 9. Runtime & distribution: single-binary edge install (language) — longer-horizon, gated
+
+Python is the right foundation for the *plugin* surface — dynamic per-CLI
+plugins and the declared-capability manifest are a Python strength, and "cover
+every CLI via a plugin" is a core stance; a wholesale Rust/Go rewrite would
+regress exactly that. The one place another language would genuinely help is
+**distribution**: a static single binary ("copy one file, run it", no
+interpreter or install step) suits constrained / edge hosts better than a Python
+runtime plus a dependency. Footprint and speed are *not* reasons — the
+supervisor's ~24 MB RSS is negligible against a GB-scale agent, and all internal
+scheduling is already event-based (run time is model-latency-bound, not
+CPU-bound in our code).
+
+Held for an explicit decision, gated on two triggers: (a) the host-health /
+pre-OOM edge (item 1) is proven and stable — you do not rewrite a moving,
+unproven core; and (b) a distribution benchmark shows single-binary install is
+the binding constraint. Even then, try Python-native single-binary packaging
+first (a self-contained bundle) before any rewrite. If a rewrite is ever
+warranted, the realistic shape is a small, stable core of the host-health / reap
+logic in Rust or Go with the plugin layer staying Python or a declarative
+format — a hybrid whose language boundary is the hard part, not a full port.
+
+## 10. Per-CLI session-directory resolution
+
+Resolve each CLI's session directory via its own environment precedence rather
+than a hardcoded default (never assume `~/.pi` / `~/.claude` / etc.). Ties to
+the existing work_dir-resolution work.
+
+## 11. Test the resume boot-guard's per-phase branch
+
+The boot guard that rejects a static resume flag already present in a command is
+tested for the base agent but not the per-phase `[phases.<name>.agent]` override
+branch. The override loop is correct by construction but untested — one small
+test.
+
+## 12. `_tail_events` / `_tail_events_jsonl` duplication
+
+Three event-stream tailers now exist at deliberately different scopes, and they
+are not accidental copies:
+
+- `cli/events_cmd.py:_tail_events` — current-month-scoped
+  (`_current_month_events_file`), resets its offset to `0` on truncation.
+- `_monitor_state.py:_tail_events_jsonl` — globs every `events-*.jsonl`;
+  re-exported through the `monitor.py` facade. It moved out of `api.py` in the
+  0.3.0 api split (`_install`/`_lifecycle`/`_observe`).
+- `_throttle.py:_tail_events` — the newest two monthly files
+  (`glob("events-*.jsonl")[-2:]`).
+
+Collapsing them means first deciding which scope is correct for each caller — a
+structural decision, not a literal swap. (The older "character-identical
+kind-read loop in `_throttle.py` and `monitor.py`" sub-concern has evaporated:
+`monitor.py` no longer carries that loop — it moved to `_monitor_detectors.py`
+and grew its own reset-ladder logic — and `_throttle.py` iterates forward over
+the tailer generator, so the only shared text left is the single line
+`kind = ev.get("event")`.)
+
+## 13. `stash_orphan` loses the ref when the post-push listing fails
+
+`vcs_state.stash_orphan` returns `None` in three cases; two are true no-ops. The
+third — `git stash push` succeeded but the follow-up `git stash list` failed —
+means the WIP *is* stashed yet callers read "nothing stashed" and report the
+tree as ignored. It is already documented in-code as a KNOWN GAP and judged
+effectively unreachable (a listing that fails microseconds after a push that
+just succeeded in the same repo).
+
+Deferred because closing it is a naming decision, not cleanup: no event kind
+carries the meaning "stashed but ref lost" (`orphan_stash_failed` would be wrong
+— the stash exists). Left as-is until that kind is designed.

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

@@ -5,6 +5,29 @@ 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.11] - 2026-09-17
+
+### Added
+- Host disk/inode-growth WARNING detector: `[monitor.host_health.disk]` gains `disk_growth_pct_per_hr_warning`/`inode_growth_pct_per_hr_warning` (default 5.0%/hr each); a new `disk_growth` monitor alert kind (observability-only, no action taken).
+- `agent_runner.events.register_plugin_kind(name)` restores a namespaced custom-event-kind affordance for out-of-tree plugins, validated against the builtin-kind namespace.
+
+### Verified
+- Pre-OOM host-pressure terminate: small-host PSI/swap calibration pinned as always-on tests-of-record, plus a gated real-cgroup property test (`AGENT_RUNNER_E2E_PI`) run live on a ~0.5 GB host — sustained host PSI-full ≥ 60 (measured 69–77 over 3 samples) terminated and reaped the agent with the host still responsive and no cgroup OOM kill; reproduced across two clean runs.
+
+### Docs
+- `docs/migrations/0.3.md` clarifies the 0.3.9 seam-subtraction adaptation contract (fold-in via `post_round_hooks`, `event_kinds` replacement) and documents `register_plugin_kind`.
+
+No config migration required. `peek --json` schema stays `2.6`.
+
+## [0.3.10] - 2026-09-17
+
+### Added
+- Cross-round resume for `pi`: `PluginManifest.resume_flag` (pi = `--session-id`) lets a preset declare an idempotent session flag; `serve` mints one session id per phase and publishes it via `AGENT_RUNNER_RESUME_FLAG`/`AGENT_RUNNER_RESUME_SESSION_ID`, and the round child appends `[flag, id]` to its command. claude/gemini/codewhale/kimi are untouched (`resume_flag` stays `None`) — later release.
+- A new `session_resumed` event records when a round reuses a prior session id.
+- Boot guard: a preset whose static command already contains its `resume_flag` token now fails config load (agent-runner injects it per round; remove the static copy).
+
+No config migration — `resume_flag` is a manifest field, not a TOML key. `peek --json` schema stays `2.6`.
+
 ## [0.3.9] - 2026-09-17
 
 ### Changed

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: cli-agent-runner
-Version: 0.3.9
+Version: 0.3.11
 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
@@ -51,7 +51,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  14 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -88,7 +88,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 14 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
@@ -113,10 +113,10 @@ Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
 `serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
 of [`docs/configuration.md`](docs/configuration.md).
 
-## Monitor: 13 detectors
+## Monitor: 14 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`disk_growth`, `mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
 `network_fail`, `rate_limit_active`, `anomaly_repetitive_active`,
 `supervisor_stale`. `mem_pressure` also drives a separate serve-loop
 admission gate that defers or terminates rounds under real memory pressure —

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/README.md

@@ -13,7 +13,7 @@ full disks, runaway memory.
 
 ```
 ┌──────────────────────────────────────────┐
-│ Layer 3: The Witness (monitor)           │  13 detectors + auto-stop
+│ Layer 3: The Witness (monitor)           │  14 detectors + auto-stop
 ├──────────────────────────────────────────┤
 │ Layer 2: The Loop (serve)                │  signal-trapping restart loop
 ├──────────────────────────────────────────┤
@@ -50,7 +50,7 @@ Full walkthrough: [`docs/quickstart.md`](docs/quickstart.md).
 |---|---|
 | `init` / `install` / `uninstall` | `peek` — state snapshot |
 | `start` / `stop` / `kill` | `watch` — peek in a refresh loop |
-| `restart` / `status` | `monitor` — 13 detectors, alerts, auto-stop |
+| `restart` / `status` | `monitor` — 14 detectors, alerts, auto-stop |
 | `round` / `serve` | `events` — query / stream events.jsonl |
 | `upgrade` / `migrate` | `doctor` — read-only pre-flight |
 
@@ -75,10 +75,10 @@ Optionally pause the loop during off-hours: `[schedule]` run/pause windows gate
 `serve` (override with `serve --ignore-schedule`) — see the `[schedule]` section
 of [`docs/configuration.md`](docs/configuration.md).
 
-## Monitor: 13 detectors
+## Monitor: 14 detectors
 
 Notify only: `timeout_rate`, `hung`, `orphan_chain`, `disk_warning`,
-`mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
+`disk_growth`, `mem_pressure`, `mem_pressure_gate_inert`, `mem_signal_unavailable`,
 `network_fail`, `rate_limit_active`, `anomaly_repetitive_active`,
 `supervisor_stale`. `mem_pressure` also drives a separate serve-loop
 admission gate that defers or terminates rounds under real memory pressure —

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/_emit/__init__.py

@@ -65,6 +65,7 @@ from agent_runner._emit.serve import (  # noqa: F401 — public re-export
     emit_schedule_paused,
     emit_schedule_phase_skipped,
     emit_schedule_resumed,
+    emit_session_resumed,
     emit_stalled_no_progress,
     emit_stop_file_detected,
 )
@@ -104,6 +105,7 @@ __all__ = [
     "emit_schedule_paused",
     "emit_schedule_phase_skipped",
     "emit_schedule_resumed",
+    "emit_session_resumed",
     "emit_stale_index_lock_cleared",
     "emit_stalled_no_progress",
     "emit_stop_file_detected",

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/_emit/serve.py

@@ -191,3 +191,15 @@ def emit_schedule_resumed(log_dir: Path, *, paused_for_s: int) -> None:
     from agent_runner.events import SCHEDULE_RESUMED, emit
 
     emit(log_dir, SCHEDULE_RESUMED, paused_for_s=paused_for_s)
+
+
+def emit_session_resumed(log_dir: Path, *, session_id: str, phase: str = "") -> None:
+    """Emit session_resumed when serve resumes an existing agent session on a
+    non-first round of an epoch (the runtime property peek cannot show). ``phase``
+    is omitted when empty so the base (no-override) phase stays a clean payload."""
+    from agent_runner.events import SESSION_RESUMED, emit
+
+    fields = {"session_id": session_id}
+    if phase:
+        fields["phase"] = phase
+    emit(log_dir, SESSION_RESUMED, **fields)

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/_monitor_detectors.py

@@ -1,6 +1,6 @@
 """Pure anomaly detectors over events + metrics + log tails.
 
-13 built-in detectors. Two trigger ``auto_action="stop_service"``:
+14 built-in detectors. Two trigger ``auto_action="stop_service"``:
   * oauth_fail  — agent-reported auth failures, or an auth pattern in
     short-exit logs (retrying burns API quota)
   * disk_critical — disk_used_pct > 95% (writing more risks corruption)
@@ -218,6 +218,93 @@ def detect_disk_critical(
     )
 
 
+def detect_disk_growth(
+    metrics: list[dict[str, Any]],
+    *,
+    growth_window_s: int = 1800,
+    disk_growth_pct_per_hr_warning: float = 5.0,
+    inode_growth_pct_per_hr_warning: float = 5.0,
+) -> Alert | None:
+    """WARNING when disk_used_pct and/or inode_used_pct is climbing faster than
+    its configured %/hr floor -- a generalized host-disk/inode-pressure signal
+    (pi's cross-round resume amplifies session-log growth; not pi-specific).
+
+    Rate is Δpct over the OLDEST metrics sample landing within
+    ``growth_window_s`` of the LATEST sample's ``ts`` (``agent_runner``'s
+    ``parse_iso_ms``), divided by the elapsed hours between them -- real
+    metrics land at variable wall-clock gaps, so a fixed-interval
+    ``(cur - prev)`` delta would misjudge the rate whenever polls drift.
+    Fewer than two samples inside the window (a cold start, or every prior
+    sample already aged out) returns ``None`` -- no baseline, no rate.
+
+    Observability only BY DESIGN, mirroring
+    :func:`host_health.cgroup_growth_rate_pressure`: unlike
+    :func:`detect_disk_critical`, this NEVER sets ``auto_action`` -- a
+    growth-rate signal is for an operator/plugin to act on, not a kill
+    trigger. Carries BOTH the disk and inode rate dims on one alert (not two
+    separate alert kinds) even when only one crosses its floor, so a reader
+    always sees the other dimension's current rate for context.
+    """
+    latest_ts_raw = _latest(metrics, "ts")
+    latest_disk = _latest(metrics, "disk_used_pct")
+    if latest_ts_raw is None or latest_disk is None:
+        return None
+    latest_ts = parse_iso_ms(latest_ts_raw)
+    latest_inode = _latest(metrics, "inode_used_pct")
+
+    baseline: dict[str, Any] | None = None
+    baseline_ts: datetime | None = None
+    for m in metrics:
+        ts_raw = m.get("ts")
+        if ts_raw is None or "disk_used_pct" not in m:
+            continue
+        ts = parse_iso_ms(ts_raw)
+        age_s = (latest_ts - ts).total_seconds()
+        if age_s < 0 or age_s > growth_window_s:
+            continue  # future-dated, or aged out of the growth window
+        # metrics is chronologically ascending, so the first in-window sample
+        # is the oldest -- the widest baseline; no later sample can be older.
+        baseline, baseline_ts = m, ts
+        break
+
+    if baseline is None or baseline_ts is None or baseline_ts >= latest_ts:
+        return None  # no earlier in-window sample to diff against
+    elapsed_hr = (latest_ts - baseline_ts).total_seconds() / 3600.0
+    if elapsed_hr <= 0:
+        return None
+
+    disk_rate = (latest_disk - baseline["disk_used_pct"]) / elapsed_hr
+    baseline_inode = baseline.get("inode_used_pct")
+    inode_rate = (
+        (latest_inode - baseline_inode) / elapsed_hr
+        if latest_inode is not None and baseline_inode is not None
+        else None
+    )
+
+    disk_trip = disk_rate >= disk_growth_pct_per_hr_warning
+    inode_trip = inode_rate is not None and inode_rate >= inode_growth_pct_per_hr_warning
+    if not disk_trip and not inode_trip:
+        return None
+
+    bits = []
+    if disk_trip:
+        bits.append(f"disk +{disk_rate:.1f}%/hr (>= {disk_growth_pct_per_hr_warning})")
+    if inode_trip:
+        bits.append(f"inode +{inode_rate:.1f}%/hr (>= {inode_growth_pct_per_hr_warning})")
+    return _alert(
+        "disk_growth",
+        "warning",
+        f"{' and '.join(bits)} over the last {growth_window_s}s",
+        {
+            "disk_pct_per_hr": round(disk_rate, 2),
+            "disk_threshold_pct_per_hr": disk_growth_pct_per_hr_warning,
+            "inode_pct_per_hr": round(inode_rate, 2) if inode_rate is not None else None,
+            "inode_threshold_pct_per_hr": inode_growth_pct_per_hr_warning,
+            "window_s": growth_window_s,
+        },
+    )
+
+
 def _latest_two(metrics: list[dict[str, Any]]) -> tuple[dict[str, Any], dict[str, Any]]:
     """Return (current, previous) full metric dicts -- the last two history
     entries (or ``{}`` when shorter). The mem-pressure ladder needs a delta

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/_monitor_registry.py

@@ -26,6 +26,7 @@ KNOWN_ALERT_KINDS: frozenset[str] = frozenset(
         "orphan_chain",
         "disk_warning",
         "disk_critical",
+        "disk_growth",
         "mem_pressure",
         "mem_signal_unavailable",
         "mem_pressure_gate_inert",

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/_plugin_manifest.py

@@ -43,6 +43,13 @@ class PluginManifest:
     SIGTERM-first at the reap site (today's behavior), never "skip the first
     signal"."""
 
+    resume_flag: str | None = None
+    """The flag that carries a supervisor-chosen session id on EVERY round for a
+    CLI whose session flag is IDEMPOTENT (create-or-resume). pi = "--session-id".
+    ``None`` = no resume (today's cold start). Resolved ONLY by
+    ``resolve_resume_flag``; ``__post_init__`` rejects an empty string. Source-
+    verified per preset (pi's --session-id is idempotent), NEVER assumed."""
+
     def __post_init__(self) -> None:
         # Errors-unlikely-by-construction: an unknown signal name (or a
         # freeze/zero-grace one like SIGSTOP/SIGKILL) is unrepresentable -- it
@@ -52,6 +59,10 @@ class PluginManifest:
                 "cooperative_stop must be one of {None, 'SIGTERM', 'SIGINT'}, "
                 f"got {self.cooperative_stop!r}"
             )
+        if self.resume_flag is not None and not self.resume_flag:
+            raise ValueError(
+                f"resume_flag must be None or a non-empty flag string, got {self.resume_flag!r}"
+            )
 
 
 _LOADED_MANIFESTS: list[PluginManifest] = []
@@ -102,6 +113,21 @@ def resolve_cooperative_signal(agent_binary: str | None) -> signal.Signals | Non
     return _COOPERATIVE_SIGNALS.get(_cooperative_stop_for_name(agent_binary))
 
 
+def resolve_resume_flag(agent_binary: str | None) -> str | None:
+    """The resume flag the agent named `agent_binary` declares, or None when no
+    such manifest is registered (or it declares no resume). THE registry lookup
+    for resume -- sibling to resolve_cooperative_signal, the SAME
+    ``m.name == agent_binary`` join (so it stays correct whenever a preset's
+    manifest name is kept equal to its agent binary). serve resolves it once
+    per phase and publishes the id via env so the round child never
+    re-derives. No signal table: the flag string IS what serve publishes and
+    the child appends, so the scan IS the resolve."""
+    for m in _LOADED_MANIFESTS:
+        if m.name == agent_binary:
+            return m.resume_flag
+    return None
+
+
 def cooperative_signal_from_name(name: str | None) -> signal.Signals | None:
     """Map a published cooperative-stop signal NAME (e.g. from
     AGENT_RUNNER_COOPERATIVE_STOP_SIGNAL) back to a ``signal.Signals`` through

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/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.9'
-__version_tuple__ = version_tuple = (0, 3, 9)
+__version__ = version = '0.3.11'
+__version_tuple__ = version_tuple = (0, 3, 11)
 
 __commit_id__ = commit_id = None

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/agent_runtime.py

@@ -634,6 +634,7 @@ def run(
     clock: Clock = SYSTEM_CLOCK,
     reap_grace_s: int = REAP_GRACE_S,
     cooperative_first_signal: signal.Signals = signal.SIGTERM,
+    resume_args: tuple[str, ...] = (),
 ) -> RunResult:
     """Spawn the agent subprocess and wait for exit or timeout.
 
@@ -653,6 +654,14 @@ def run(
     cooperative_stop / standalone `agent-runner round`), so every existing caller
     is unchanged.
 
+    resume_args: ``[flag, session_id]`` appended after ``command`` and before
+    the prompt args, for a resume-capable agent picking its session back up
+    across rounds. The id is minted once by the caller's own env-published
+    single-source (``runner._resolve_resume_args``) and copied verbatim here --
+    this module never mints or derives one (no ``os.environ`` read for the
+    session id; see the module docstring). Defaults to ``()``, so every
+    existing caller's argv is byte-identical to before.
+
     work_dir: the agent child's working directory; callers pass the
     already-absolute cfg.runtime.work_dir. CLIs with no --cwd flag of their
     own (e.g. pi) depend on this.
@@ -760,10 +769,11 @@ def run(
     # template for stdin mode, but run() must be safe even if called
     # directly with a mismatched template. In stdin mode, never substitute
     # {prompt} into argv — build it verbatim so the prompt cannot reach argv.
+    resumed_command = list(spawn_command) + list(resume_args)
     argv = (
-        list(spawn_command) + list(prompt_arg_template)
+        list(resumed_command) + list(prompt_arg_template)
         if stdin_mode
-        else _build_argv(spawn_command, prompt_arg_template, prompt)
+        else _build_argv(resumed_command, prompt_arg_template, prompt)
     )
     # PWD pinned last — it mirrors cwd= (a correctness pin, not a knob), so
     # an [agent.env] PWD cannot silently diverge from where the child runs.

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/api.py

@@ -62,6 +62,7 @@ from agent_runner._emit import (  # noqa: E402,F401 — intentional bottom re-ex
     emit_schedule_paused,
     emit_schedule_phase_skipped,
     emit_schedule_resumed,
+    emit_session_resumed,
     emit_stale_index_lock_cleared,
     emit_stalled_no_progress,
     emit_stop_file_detected,

{cli_agent_runner-0.3.9 → cli_agent_runner-0.3.11}/agent_runner/builtin_plugins/pi.py

@@ -281,5 +281,8 @@ def _is_auth_error(text: str | None) -> bool:
 
 
 PLUGIN = PluginManifest(
-    name="pi", post_round_hooks=(PiErrorDetector(),), cooperative_stop="SIGTERM"
+    name="pi",
+    post_round_hooks=(PiErrorDetector(),),
+    cooperative_stop="SIGTERM",
+    resume_flag="--session-id",
 )