fleetproof 0.6.1__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. {fleetproof-0.6.1/src/fleetproof.egg-info → fleetproof-0.7.0}/PKG-INFO +1 -1
  2. {fleetproof-0.6.1 → fleetproof-0.7.0}/pyproject.toml +1 -1
  3. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/__init__.py +1 -1
  4. fleetproof-0.7.0/src/fleetproof/_version.py +8 -0
  5. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/checker.py +10 -3
  6. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/checks.py +21 -2
  7. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/cli.py +180 -8
  8. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/hookgate.py +310 -17
  9. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/ledger.py +153 -4
  10. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/report.py +12 -0
  11. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/runlog.py +35 -0
  12. {fleetproof-0.6.1 → fleetproof-0.7.0/src/fleetproof.egg-info}/PKG-INFO +1 -1
  13. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof.egg-info/SOURCES.txt +2 -0
  14. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_cli.py +7 -5
  15. fleetproof-0.7.0/tests/test_v070.py +473 -0
  16. {fleetproof-0.6.1 → fleetproof-0.7.0}/LICENSE +0 -0
  17. {fleetproof-0.6.1 → fleetproof-0.7.0}/README.md +0 -0
  18. {fleetproof-0.6.1 → fleetproof-0.7.0}/setup.cfg +0 -0
  19. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/__main__.py +0 -0
  20. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/config.py +0 -0
  21. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/controls.py +0 -0
  22. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/__init__.py +0 -0
  23. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/fixtures/README.md +0 -0
  24. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/fixtures/http_json_field.sample.json +0 -0
  25. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/http_json_field.py +0 -0
  26. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/py_tests_pinned.py +0 -0
  27. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/library/worktree_landed.py +0 -0
  28. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/phase.py +0 -0
  29. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/telemetry.py +0 -0
  30. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof/telemetry_export.py +0 -0
  31. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof.egg-info/dependency_links.txt +0 -0
  32. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof.egg-info/entry_points.txt +0 -0
  33. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof.egg-info/requires.txt +0 -0
  34. {fleetproof-0.6.1 → fleetproof-0.7.0}/src/fleetproof.egg-info/top_level.txt +0 -0
  35. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_adversarial_regressions.py +0 -0
  36. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_checker.py +0 -0
  37. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_checks.py +0 -0
  38. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_controls.py +0 -0
  39. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_hookgate.py +0 -0
  40. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_ledger.py +0 -0
  41. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_library.py +0 -0
  42. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_phase.py +0 -0
  43. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_report.py +0 -0
  44. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_runlog.py +0 -0
  45. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_telemetry.py +0 -0
  46. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_telemetry_export.py +0 -0
  47. {fleetproof-0.6.1 → fleetproof-0.7.0}/tests/test_version_surfaces.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fleetproof
3
- Version: 0.6.1
3
+ Version: 0.7.0
4
4
  Summary: Independent, out-of-band verification for agent fleets.
5
5
  Author: Gathrazio
6
6
  License: MIT
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "fleetproof"
7
- version = "0.6.1"
7
+ version = "0.7.0"
8
8
  description = "Independent, out-of-band verification for agent fleets."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -5,7 +5,7 @@ The agent may author the checks; it never executes and grades its own work.
5
5
 
6
6
  from __future__ import annotations
7
7
 
8
- __version__ = "0.6.1"
8
+ from ._version import __version__
9
9
 
10
10
  from .runlog import (
11
11
  RunRecord,
@@ -0,0 +1,8 @@
1
+ """Single source of the package version, importable from the lowest layer.
2
+
3
+ Lives below :mod:`fleetproof.runlog` so modules the package ``__init__``
4
+ itself imports (runlog, ledger) can stamp the version into records without a
5
+ circular import. ``fleetproof.__version__`` re-exports this value.
6
+ """
7
+
8
+ __version__ = "0.7.0"
@@ -309,12 +309,19 @@ def _grade(check: Check, returncode: int | None, stdout: str, stderr: str, cwd:
309
309
  pattern = check.expect["pattern"]
310
310
  # Exit code gates the match (finding H1): a failing command whose *error
311
311
  # text* happens to contain the pattern — e.g. a tool echoing
312
- # "ALL_TESTS_PASSED is not a flag" — must not read as a pass.
313
- if returncode != 0:
312
+ # "ALL_TESTS_PASSED is not a flag" — must not read as a pass. The
313
+ # per-check `consult_output_on_nonzero` opt-in lifts the gating for a
314
+ # command that completed non-zero (a test script that exits 1 on
315
+ # failure yet prints the summary line the regex asserts); a command
316
+ # that never completed still failed above.
317
+ if returncode != 0 and not check.consult_output_on_nonzero:
314
318
  return False, f"exit {returncode} (expected 0); output not consulted for /{pattern}/"
315
319
  combined = f"{stdout}\n{stderr}"
316
320
  ok = re.search(pattern, combined) is not None
317
- return ok, ("matched" if ok else "no match") + f" for /{pattern}/"
321
+ detail = ("matched" if ok else "no match") + f" for /{pattern}/"
322
+ if returncode != 0:
323
+ detail += f" (exit {returncode}; output consulted per consult_output_on_nonzero)"
324
+ return ok, detail
318
325
 
319
326
  if kind == "file_exists":
320
327
  raw_path = check.expect["path"]
@@ -72,10 +72,11 @@ _VALID_EXPECT_KEYS = {"exit", "regex", "file_exists"}
72
72
  # manifest pinned under an older release must not start failing mid-flight.
73
73
  SPEC_CHECK_KEYS = frozenset({
74
74
  "id", "run", "expect", "block", "description", "tier", "owner", "redact",
75
- "succeeded_by",
75
+ "succeeded_by", "consult_output_on_nonzero",
76
76
  })
77
77
  MANIFEST_CHECK_KEYS = frozenset({
78
78
  "id", "cmd", "run", "expect", "block", "description", "owner", "redact",
79
+ "consult_output_on_nonzero",
79
80
  })
80
81
 
81
82
 
@@ -192,6 +193,14 @@ class Check:
192
193
  # this check, must share its tier, and the chain must not cycle. See
193
194
  # :mod:`fleetproof.phase`. Additive: absent reads as None.
194
195
  succeeded_by: str | None = None
196
+ # Regex checks gate the match on exit 0 (finding H1: a failing command's
197
+ # error text must not pass a content assertion). On a test script that
198
+ # already exits non-zero on failure, that gating makes a regex check add
199
+ # nothing over the exit check — measured in a harness-free field trial on
200
+ # macOS. Opting in here lets the regex decide on a completed-but-nonzero
201
+ # command; a command that never completed still fails. Additive, default
202
+ # off: every existing spec keeps H1's exact semantics.
203
+ consult_output_on_nonzero: bool = False
195
204
 
196
205
  def describe_run(self) -> str | None:
197
206
  """The command for display: string form verbatim, argv form joined
@@ -534,6 +543,15 @@ def _parse_check(entry: Any, index: int, *, where: str | None = None,
534
543
 
535
544
  expect = _normalize_expect(entry.get("expect", "exit0"), cid, where)
536
545
 
546
+ consult = entry.get("consult_output_on_nonzero", False)
547
+ if not isinstance(consult, bool):
548
+ raise CheckSpecError(
549
+ f"{where} ({cid}): 'consult_output_on_nonzero' must be true or false.")
550
+ if consult and expect["kind"] != "regex":
551
+ raise CheckSpecError(
552
+ f"{where} ({cid}): 'consult_output_on_nonzero' only applies to a "
553
+ "'regex' expect — other kinds never consult output.")
554
+
537
555
  # A file_exists check may have no command; every other kind needs one.
538
556
  if run is None and expect["kind"] != "file_exists":
539
557
  raise CheckSpecError(
@@ -542,7 +560,8 @@ def _parse_check(entry: Any, index: int, *, where: str | None = None,
542
560
 
543
561
  return Check(id=cid, run=run, expect=expect, block=block, description=description,
544
562
  tier=tier, owner=owner, redact=tuple(redact_raw),
545
- succeeded_by=succeeded_by.strip() if succeeded_by else None)
563
+ succeeded_by=succeeded_by.strip() if succeeded_by else None,
564
+ consult_output_on_nonzero=consult)
546
565
 
547
566
 
548
567
  def _normalize_expect(expect: Any, cid: str, where: str) -> dict[str, Any]:
@@ -87,6 +87,7 @@ from .hookgate import (
87
87
  DEFAULT_ARMING_TIER,
88
88
  LANE_NEVER_DISARMED,
89
89
  load_arming,
90
+ stop_block_status,
90
91
  tier_arming,
91
92
  tier_set_meta,
92
93
  record_tool_main,
@@ -108,10 +109,12 @@ from .ledger import (
108
109
  REASON_ABANDONED,
109
110
  REASON_OPERATOR_CLOSE,
110
111
  REASON_PARKED_PREFIX,
112
+ REASON_SWEEP_IDLE,
111
113
  TIER_SOURCE_DECLARED,
112
114
  TIER_SOURCE_DEFAULTED,
113
115
  VALID_TERMINATE_REASONS,
114
116
  LedgerError,
117
+ advisory_failure_line,
115
118
  advisory_verdict_line,
116
119
  close_dispatch,
117
120
  create_dispatch,
@@ -119,6 +122,7 @@ from .ledger import (
119
122
  list_dispatches,
120
123
  list_orphan_stops,
121
124
  list_ungraded_terminations,
125
+ list_verified_with_advisory_failures,
122
126
  load_dispatch,
123
127
  record_report,
124
128
  ungraded_termination_line,
@@ -566,11 +570,22 @@ def _cmd_cleanup(args: argparse.Namespace) -> int:
566
570
  deleted, skipped = [], []
567
571
  if rd.exists():
568
572
  cutoff = datetime.now(timezone.utc) - timedelta(days=args.older_than_days)
569
- for run_dir in sorted(rd.iterdir()):
570
- if not run_dir.is_dir() or run_dir.name.startswith("."):
571
- continue
573
+ run_dirs = [d for d in sorted(rd.iterdir())
574
+ if d.is_dir() and not d.name.startswith(".")]
575
+ # --max-runs: keep only the newest N run dirs regardless of age. The
576
+ # ledger is never pruned by anything else, and at 5,000 recorded
577
+ # events one repo held 20,048 files with 1-2.5 s stops (a harness-free
578
+ # field trial on macOS) — age alone does not bound a busy day. Run ids
579
+ # are timestamp-prefixed, so name order is age order; the age rule
580
+ # still applies to what --max-runs keeps.
581
+ over_cap: set[str] = set()
582
+ if args.max_runs is not None and len(run_dirs) > args.max_runs:
583
+ for run_dir in run_dirs[: len(run_dirs) - args.max_runs]:
584
+ over_cap.add(run_dir.name)
585
+ for run_dir in run_dirs:
572
586
  started = _run_started_at(run_dir)
573
- if started is None or started >= cutoff:
587
+ stale = started is not None and started < cutoff
588
+ if not stale and run_dir.name not in over_cap:
574
589
  skipped.append(run_dir.name)
575
590
  continue
576
591
  if not args.dry_run:
@@ -1152,7 +1167,8 @@ def _cmd_dispatch_verify(args: argparse.Namespace) -> int:
1152
1167
  :func:`fleetproof.hookgate.verify_dispatch`.
1153
1168
  """
1154
1169
  try:
1155
- result = verify_dispatch(args.run_id, note=(args.note or "").strip() or None)
1170
+ result = verify_dispatch(args.run_id, note=(args.note or "").strip() or None,
1171
+ allow_terminal=bool(args.terminal))
1156
1172
  except LedgerError as e:
1157
1173
  _emit_error("ledger_error", str(e), args.format)
1158
1174
  return 1
@@ -1171,6 +1187,75 @@ def _cmd_dispatch_verify(args: argparse.Namespace) -> int:
1171
1187
  return 0
1172
1188
 
1173
1189
 
1190
+ def _parse_older_than(raw: str) -> timedelta:
1191
+ """``--older-than`` value: '<N>d' (days) or '<N>h' (hours), N >= 1."""
1192
+ text = (raw or "").strip().lower()
1193
+ unit = text[-1:] if text else ""
1194
+ try:
1195
+ n = int(text[:-1])
1196
+ except ValueError:
1197
+ n = 0
1198
+ if n < 1 or unit not in ("d", "h"):
1199
+ raise argparse.ArgumentTypeError(
1200
+ f"--older-than wants '<N>d' or '<N>h' (e.g. 2d, 12h); got {raw!r}.")
1201
+ return timedelta(days=n) if unit == "d" else timedelta(hours=n)
1202
+
1203
+
1204
+ def _cmd_dispatch_sweep(args: argparse.Namespace) -> int:
1205
+ """Bulk-close stale non-terminal dispatches (field ask: board hygiene).
1206
+
1207
+ A board carrying 16 stale in-fleet rows from three weeks back, parked one
1208
+ `dispatch close` at a time, is a board nobody reconciles (a field
1209
+ deployment on Windows). One command closes every non-terminal dispatch
1210
+ older than the cutoff — with ``--reason`` as an attributed park
1211
+ (``parked: <text>``), without as the machine reason ``sweep-idle``.
1212
+ ``--session`` narrows to one session; ``--dry-run`` lists without closing.
1213
+ """
1214
+ cutoff = datetime.now(timezone.utc) - args.older_than
1215
+ swept: list[str] = []
1216
+ skipped_young: int = 0
1217
+ for record in list_dispatches(session_id=args.session, non_terminal_only=True):
1218
+ started = None
1219
+ if record.started_at:
1220
+ try:
1221
+ started = datetime.fromisoformat(record.started_at)
1222
+ except ValueError:
1223
+ started = None
1224
+ if started is not None and started.tzinfo is None:
1225
+ started = started.replace(tzinfo=timezone.utc)
1226
+ # An undatable record is treated as stale, not young: the sweep exists
1227
+ # to clear rows whose records have decayed, and skipping them would
1228
+ # strand exactly those forever.
1229
+ if started is not None and started >= cutoff:
1230
+ skipped_young += 1
1231
+ continue
1232
+ if not args.dry_run:
1233
+ reason = (REASON_PARKED_PREFIX + args.reason.strip()
1234
+ if (args.reason or "").strip() else REASON_SWEEP_IDLE)
1235
+ try:
1236
+ close_dispatch(record.run_id, reason=reason)
1237
+ except LedgerError as e:
1238
+ print(f"[fleetproof] could not sweep {record.run_id}: {e}",
1239
+ file=sys.stderr)
1240
+ continue
1241
+ try:
1242
+ build_telemetry(record.run_id)
1243
+ except Exception as e:
1244
+ print(f"[fleetproof] telemetry build failed for {record.run_id}: {e}",
1245
+ file=sys.stderr)
1246
+ swept.append(record.run_id)
1247
+ if args.format == "json":
1248
+ print(json.dumps({"swept": swept, "skipped_young": skipped_young,
1249
+ "dry_run": bool(args.dry_run)}, indent=2))
1250
+ return 0
1251
+ prefix = "DRY RUN — would sweep" if args.dry_run else "Swept"
1252
+ print(f"{prefix} {len(swept)} dispatch(es); {skipped_young} younger than "
1253
+ "the cutoff left alone.")
1254
+ for run_id in swept:
1255
+ print(f" {run_id}")
1256
+ return 0
1257
+
1258
+
1174
1259
  def _format_age(started_at: str | None) -> str:
1175
1260
  """Compact ASCII age of a dispatch: '42s', '17m', '3h05m', '2d04h', or '?'."""
1176
1261
  if not started_at:
@@ -1433,10 +1518,12 @@ def _orphan_count_line(orphans: list[dict], scope_known: bool) -> str:
1433
1518
 
1434
1519
 
1435
1520
  def _cmd_fleet(args: argparse.Namespace) -> int:
1436
- _print_liveness_line(soft_when_unknown=True)
1521
+ # Liveness prints only when the answer is NO (a hook session that left no
1522
+ # hook evidence). The "unknown" line on every plain-shell `fleet` was
1523
+ # noise above the board by the twentieth call (field ask 17).
1524
+ _print_liveness_line()
1437
1525
  if args.orphans:
1438
1526
  return _cmd_fleet_orphans(args)
1439
- records = list_dispatches(session_id=args.session, non_terminal_only=args.open)
1440
1527
  # One scope rule for every footer count (orphans, ungraded, advisory):
1441
1528
  # ledger-scoped, never listing-scoped. "This session" is the --session
1442
1529
  # filter, else the hook session the CLI is running inside
@@ -1447,6 +1534,15 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1447
1534
  # session" from a session-less shell while counting every orphan on disk
1448
1535
  # (observed in a field deployment on Windows).
1449
1536
  scope_session = args.session or os.environ.get(SESSION_ID_ENV) or None
1537
+ # The ROW listing now shares that scope: two concurrent bridges in one
1538
+ # repo each read the other's rows as "still in fleet" and could not tell
1539
+ # whose they were (a field deployment on Windows, ask 13). Under a hook
1540
+ # session the board defaults to that session's rows; --all widens to the
1541
+ # whole ledger; a session-less shell keeps the whole-ledger default.
1542
+ listing_session = None if args.all else (args.session or scope_session)
1543
+ env_scoped = bool(listing_session) and not args.session
1544
+ records = list_dispatches(session_id=listing_session,
1545
+ non_terminal_only=args.open)
1450
1546
  orphans = list_orphan_stops(session_id=scope_session)
1451
1547
  ungraded = list_ungraded_terminations(scope_session)
1452
1548
  ungraded_line = ungraded_termination_line(ungraded, scope_known=bool(scope_session))
@@ -1456,6 +1552,17 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1456
1552
  advisory_graded = list_advisory_verdicts(scope_session)
1457
1553
  advisory_line = advisory_verdict_line(advisory_graded,
1458
1554
  scope_known=bool(scope_session))
1555
+ # Verified verdicts whose advisory (block:false) checks failed — the
1556
+ # finding-1a surface — and the session's stop-block budget, when spent.
1557
+ warn_verified = list_verified_with_advisory_failures(scope_session)
1558
+ warn_line = advisory_failure_line(warn_verified, scope_known=bool(scope_session))
1559
+ budget = stop_block_status(scope_session)
1560
+ budget_line = None
1561
+ if budget and budget["exhausted"]:
1562
+ budget_line = (f"bridge stop gate EXHAUSTED this session: {budget['blocks']} "
1563
+ f"blocked stop(s) > budget {budget['budget']} — the gate is "
1564
+ "standing down to advisory context and the underlying "
1565
+ "failure is UNRESOLVED. Fix it or disarm on record.")
1459
1566
  # The board echoes every disarmed gate (bridge, coordinator) whenever it
1460
1567
  # is advisory — the armed default stays quiet. Silence here is what makes
1461
1568
  # the echo a signal.
@@ -1467,6 +1574,7 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1467
1574
  "dispatches": [
1468
1575
  dict(r.to_dict(), age=_format_age(r.started_at)) for r in records
1469
1576
  ],
1577
+ "listing_session": listing_session,
1470
1578
  "orphan_stop_count": len(orphans),
1471
1579
  "terminated_ungraded_count": len(ungraded),
1472
1580
  "terminated_ungraded": [r.run_id for r in ungraded],
@@ -1475,13 +1583,22 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1475
1583
  {"run_id": r.run_id, "detail": r.verdict_detail}
1476
1584
  for r in advisory_graded
1477
1585
  ],
1586
+ "verified_with_advisory_failures": [
1587
+ {"run_id": r.run_id, "advisory_failures": r.advisory_failures}
1588
+ for r in warn_verified
1589
+ ],
1478
1590
  }
1591
+ if budget:
1592
+ payload["stop_block_budget"] = budget
1479
1593
  if advisory:
1480
1594
  payload["arming"] = arming
1481
1595
  print(json.dumps(payload, indent=2))
1482
1596
  return 0
1483
1597
  for line in arming_lines:
1484
1598
  print(line)
1599
+ if env_scoped:
1600
+ print(f"(scoped to session {_short_session(listing_session)} — "
1601
+ "`fleet --all` for the whole ledger)")
1485
1602
  if not records:
1486
1603
  print("No dispatches found.")
1487
1604
  if orphans:
@@ -1490,6 +1607,10 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1490
1607
  print(ungraded_line)
1491
1608
  if advisory_line:
1492
1609
  print(advisory_line)
1610
+ if warn_line:
1611
+ print(warn_line)
1612
+ if budget_line:
1613
+ print(budget_line)
1493
1614
  return 0
1494
1615
  print(f"{'run_id':<24} {'state':<26} {'tier':<12} {'agent':<18} "
1495
1616
  f"{'verdict':<13} {'age':>7} {'session':<14}")
@@ -1516,6 +1637,14 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1516
1637
  if "abandoned!" in labels:
1517
1638
  print("abandoned! = terminated after 3 contradicted stops; the work "
1518
1639
  "was never verified. Park it, fix the spec/tier, or re-dispatch.")
1640
+ if "no-report!" in labels:
1641
+ print("no-report! = closed after 3 empty-message stops; the agent went "
1642
+ "idle without ever reporting and the work was never verified. "
1643
+ "Re-dispatch, park, or `dispatch verify <run_id> --terminal`.")
1644
+ if any(verdict_label(r) == "verified*" for r in records):
1645
+ print("verified* = verified while one or more advisory (block:false) "
1646
+ "check(s) FAILED — the verdict stands; read the failing ids in "
1647
+ "the record before trusting what they cover.")
1519
1648
  if "parked" in labels:
1520
1649
  print("parked = terminated on purpose with a recorded reason; not "
1521
1650
  "graded further.")
@@ -1544,6 +1673,10 @@ def _cmd_fleet(args: argparse.Namespace) -> int:
1544
1673
  print(ungraded_line)
1545
1674
  if advisory_line:
1546
1675
  print(advisory_line)
1676
+ if warn_line:
1677
+ print(warn_line)
1678
+ if budget_line:
1679
+ print(budget_line)
1547
1680
  return 0
1548
1681
 
1549
1682
 
@@ -1812,8 +1945,14 @@ def build_parser() -> argparse.ArgumentParser:
1812
1945
  p_report.add_argument("-o", "--output", default=None, help="Output HTML path.")
1813
1946
  p_report.set_defaults(func=_cmd_report)
1814
1947
 
1815
- p_cleanup = sub.add_parser("cleanup", help="Delete run records older than N days.")
1948
+ p_cleanup = sub.add_parser(
1949
+ "cleanup",
1950
+ help="Delete run records older than N days; --max-runs also bounds "
1951
+ "the total kept (the ledger is otherwise never pruned).")
1816
1952
  p_cleanup.add_argument("--older-than-days", type=int, required=True)
1953
+ p_cleanup.add_argument("--max-runs", type=int, default=None,
1954
+ help="Keep at most this many newest run dirs, "
1955
+ "whatever their age.")
1817
1956
  p_cleanup.add_argument("--dry-run", action="store_true")
1818
1957
  p_cleanup.set_defaults(func=_cmd_cleanup)
1819
1958
 
@@ -2031,9 +2170,36 @@ def build_parser() -> argparse.ArgumentParser:
2031
2170
  "--note", default=None,
2032
2171
  help="Free-text note recorded on the synthetic report (why this is "
2033
2172
  "being verified out of band).")
2173
+ p_dverify.add_argument(
2174
+ "--terminal", action="store_true",
2175
+ help="Also accept a TERMINAL dispatch that carries no verdict — the "
2176
+ "false-terminal shape (an idle stop closed it while the real "
2177
+ "work finished over a path no hook sees). Reopens it on record "
2178
+ "('reopened: true' on the transition), grades, and closes. A "
2179
+ "terminal dispatch WITH a verdict is still refused: outcomes on "
2180
+ "record stay.")
2034
2181
  _add_format(p_dverify)
2035
2182
  p_dverify.set_defaults(func=_cmd_dispatch_verify)
2036
2183
 
2184
+ p_dsweep = dsub.add_parser(
2185
+ "sweep",
2186
+ help="Bulk-close stale non-terminal dispatches: everything older than "
2187
+ "--older-than (whole ledger, or --session). With --reason each "
2188
+ "closes as an attributed park ('parked: <reason>'); without, as "
2189
+ "the machine reason 'sweep-idle'. --dry-run lists first.")
2190
+ p_dsweep.add_argument("--older-than", type=_parse_older_than, required=True,
2191
+ metavar="<N>d|<N>h",
2192
+ help="Age cutoff, e.g. 2d or 12h; younger rows are left alone.")
2193
+ p_dsweep.add_argument("--session", default=None,
2194
+ help="Only sweep this session's dispatches.")
2195
+ p_dsweep.add_argument("--reason", default=None,
2196
+ help="Park each swept dispatch with this reason "
2197
+ "(recorded as 'parked: <reason>').")
2198
+ p_dsweep.add_argument("--dry-run", action="store_true",
2199
+ help="List what would be swept; close nothing.")
2200
+ _add_format(p_dsweep)
2201
+ p_dsweep.set_defaults(func=_cmd_dispatch_sweep)
2202
+
2037
2203
  p_tel = sub.add_parser("telemetry", help="Verification-telemetry surfaces.")
2038
2204
  tsub = p_tel.add_subparsers(dest="telemetry_command", required=True)
2039
2205
 
@@ -2076,6 +2242,12 @@ def build_parser() -> argparse.ArgumentParser:
2076
2242
  p_fleet.add_argument("--open", action="store_true",
2077
2243
  help="Only dispatches that have not terminated.")
2078
2244
  p_fleet.add_argument("--session", default=None, help="Filter to one session id.")
2245
+ p_fleet.add_argument("--all", action="store_true",
2246
+ help="List the whole ledger. Under a hook session the "
2247
+ "board defaults to that session's rows (two "
2248
+ "concurrent bridges in one repo could not tell "
2249
+ "whose rows were whose); a session-less shell "
2250
+ "already lists everything.")
2079
2251
  p_fleet.add_argument("--orphans", action="store_true",
2080
2252
  help="List orphan stops (unpaired SubagentStops; "
2081
2253
  "sightings, never graded) instead of dispatches.")