Skip to content

Convert Claude Code or Codex into the most intelligent Deep Research Agent. Collect, search, and synthesize web research into a persistent, searchable wiki that builds on itself. Hosted API + MCP: hyperresearch.ai

fix(runs): count fetched URLs and enforce count ceilings (#115)

Aurora92744f83fc08
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 70f6f90..ef0073c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,7 @@
- **The repo is a Codex plugin marketplace too.** `.codex-plugin/plugin.json` and `.agents/plugins/marketplace.json` publish the same `deep-research` bootstrap skill as the Claude Code plugin: `codex plugin marketplace add jordan-gibbs/hyperresearch`, then `codex plugin add hyperresearch@hyperresearch`. The skill no longer assumes Claude Code. On Codex it runs `install --target codex` and then reads the entry skill directly, because Codex discovers skills when a session starts. It gains `license` and `compatibility` frontmatter and an `agents/openai.yaml`. Codex namespaces plugin skills, so from the plugin it is `$hyperresearch:deep-research`; installed standalone with `npx skills add jordan-gibbs/hyperresearch -a codex` (to `.agents/skills/deep-research/`) it is `$deep-research`. The `openai.yaml` starter prompt names the skill in words rather than by a `$` mention that would only match one of those. The README now leads with Claude Code and Codex install paths side by side.
- **`run resume` follows the tier step 1 declared.** A run is initialized with the installed gear's step list, and step 1 can reclassify it (usually to `light`) in `prompt-decomposition.json`. The ship gate already honoured that tier; `resume_position` did not, so a light-tier run that finished step 2 was told to resume at step 3, a step its tier skips. `run resume`, `run status` and the Codex Stop gate now use the declared tier's steps. Found during the first live Codex run.
- **Codex bench harness rebuilt (`codex_bench/`).** Each query runs in its own git-initialized project set up by `install --target codex`, with the prompt in `research/prompt.txt` and the inline-citation wrapper contract. The session is one `codex exec` under the workspace-write-plus-network sandbox, with JSONL events captured. `result.json` records whether the pipeline ran: vault note count, manifest steps done and not done, tier, subagent spawns, sandbox rejections, and `run verify`. An inline answer that skipped the vault is reported as `PIPELINE_SKIPPED`. `--dry-run` sets up the run dir and prints the exact `codex exec` command without running it. There are no dollar fields.
+- **Run spend counters and count ceilings (#92).** `hpr run step --status done` and `hpr run reconcile` count tagged notes and distinct fetched URLs linked to those notes in the vault DB, including HTML and PDFs. Optional `hpr run init --max-sources` / `--max-notes` ceilings block at step boundaries. `run resume` or `run step --status done --force` can clear a count block up to three times; the same count stays clear until it increases, and a fourth clear rejects the step. Agent-reported `estimated_usd` stays unchanged; `--budget` stays inert unless something calls `hpr run spend`. Real runs get count ceilings only when the entry skill passes them to `run init`.
## [0.12.0] - 2026-09-24
diff --git a/src/hyperresearch/cli/run_cmd.py b/src/hyperresearch/cli/run_cmd.py
index 9febabb..8729967 100644
--- a/src/hyperresearch/cli/run_cmd.py
+++ b/src/hyperresearch/cli/run_cmd.py
@@ -46,6 +46,8 @@ def run_init(
vault_tag: str = typer.Argument(..., help="Collision-safe run tag (mint via `hyperresearch vault-tag <slug>`)"),
profile: str = typer.Option("full", "--profile", help="Pipeline profile for this run"),
budget: float | None = typer.Option(None, "--budget", help="Hard ceiling on estimated API-equivalent spend (the run blocks when the estimate crosses it; a value measure, not a bill, on subscription billing)"),
+ max_sources: int | None = typer.Option(None, "--max-sources", help="Observable ceiling on fetched source URLs linked to vault_tag-tagged notes; checked at step-done"),
+ max_notes: int | None = typer.Option(None, "--max-notes", help="Observable ceiling on notes tagged with this run's vault_tag; checked at step-done"),
query_file: str | None = typer.Option(None, "--query-file", help="File whose verbatim contents become runs/<tag>/query.md"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
@@ -59,7 +61,15 @@ def run_init(
if query_file:
query = Path(query_file).read_text(encoding="utf-8-sig")
try:
- manifest = init_run(vault, vault_tag, profile=profile, budget_usd=budget, query=query)
+ manifest = init_run(
+ vault,
+ vault_tag,
+ profile=profile,
+ budget_usd=budget,
+ query=query,
+ max_sources=max_sources,
+ max_notes=max_notes,
+ )
except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
@@ -73,6 +83,11 @@ def run_init(
else:
console.print(f"[green]Run initialized:[/] {data['run_dir']}")
console.print(f" profile: {manifest['profile']} budget: {manifest.get('budget_usd')}")
+ if manifest.get("max_sources") is not None or manifest.get("max_notes") is not None:
+ console.print(
+ f" ceilings: max_sources={manifest.get('max_sources')} "
+ f"max_notes={manifest.get('max_notes')}"
+ )
@app.command("status")
@@ -119,6 +134,16 @@ def run_status(
)
if summary.get("possibly_stalled"):
console.print(" [yellow]possibly stalled — no manifest update recently[/]")
+ if summary.get("status") == "blocked" and summary.get("blocked_on") in (
+ "max_sources",
+ "max_notes",
+ ):
+ spend = summary.get("spend", {})
+ console.print(
+ f" [yellow]blocked on {summary['blocked_on']} — "
+ f"{spend.get('sources_fetched', 0)} sources / "
+ f"{spend.get('notes_written', 0)} notes[/]"
+ )
resume = summary["resume"]
console.print(f" done: {', '.join(resume['done_steps']) or '-'}")
console.print(f" next: {resume['next_step'] or '(complete)'}")
@@ -163,12 +188,26 @@ def run_resume(
) -> None:
"""Print the exact position a recovering orchestrator should continue from."""
from hyperresearch.core.hooks import step_skill_slug
- from hyperresearch.core.runs import RunError, load_manifest, run_resume_position, set_status
+ from hyperresearch.core.runs import (
+ RunError,
+ clear_count_block,
+ load_manifest,
+ run_resume_position,
+ set_status,
+ )
vault = _vault_or_exit(json_output)
tag = _resolve_tag(vault, vault_tag, json_output)
try:
manifest = load_manifest(vault, tag)
+ if manifest["status"] == "blocked" and manifest.get("blocked_on") in (
+ "max_sources", "max_notes"
+ ):
+ manifest = clear_count_block(vault, tag)
+ elif manifest["status"] in ("paused", "blocked", "failed"):
+ manifest = set_status(vault, tag, "running")
+ position = run_resume_position(vault, manifest)
+ run_dir = str(vault.run_dir(tag))
except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
@@ -176,13 +215,9 @@ def run_resume(
console.print(f"[red]Error:[/] {e}")
raise typer.Exit(1)
- position = run_resume_position(vault, manifest)
- if manifest["status"] in ("paused", "blocked", "failed"):
- set_status(vault, tag, "running")
-
data = {
"vault_tag": tag,
- "run_dir": str(vault.run_dir(tag)),
+ "run_dir": run_dir,
"profile": manifest["profile"],
**position,
# Looked up from the installer's step-skill roster, not rebuilt by
@@ -288,14 +323,19 @@ def run_step(
step: str = typer.Argument(..., help='Step id ("1", "1.5", "11g", ...)'),
status: str = typer.Option(..., "--status", "-s", help="pending|running|done|skipped|failed"),
chapter: str | None = typer.Option(None, "--chapter", help="Chapter id for chaptered steps (e.g. ch3)"),
+ force: bool = typer.Option(False, "--force", help="Clear a max_sources/max_notes block so this done can proceed"),
json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
) -> None:
- """Record a step-status transition in the manifest."""
+ """Record a step-status transition in the manifest.
+
+ On --status done, reconciles vault_tag-filtered counts and applies
+ --max-sources / --max-notes. A blocked run needs --force to accept done.
+ """
from hyperresearch.core.runs import RunError, set_step
vault = _vault_or_exit(json_output)
try:
- manifest = set_step(vault, vault_tag, step, status, chapter=chapter)
+ manifest = set_step(vault, vault_tag, step, status, chapter=chapter, force=force)
except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
@@ -340,6 +380,37 @@ def run_spend(
console.print(f" spend: {data['spend']} status: {data['status']}")
[email protected]("reconcile")
+def run_reconcile(
+ vault_tag: str | None = typer.Argument(None, help="Run tag (default: newest run)"),
+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),
+) -> None:
+ """Fold vault_tag-filtered notes/fetched URLs into spend counters (issue #92)."""
+ from hyperresearch.core.runs import RunError, reconcile_spend_from_disk
+
+ vault = _vault_or_exit(json_output)
+ tag = _resolve_tag(vault, vault_tag, json_output)
+ try:
+ manifest = reconcile_spend_from_disk(vault, tag)
+ except (RunError, VaultError) as e:
+ if json_output:
+ output(error(str(e), "RUN_ERROR"), json_mode=True)
+ else:
+ console.print(f"[red]Error:[/] {e}")
+ raise typer.Exit(1)
+ data = {
+ "vault_tag": tag,
+ "spend": manifest["spend"],
+ "status": manifest["status"],
+ "blocked_on": manifest.get("blocked_on"),
+ }
+ if json_output:
+ output(success(data, vault=str(vault.root)), json_mode=True)
+ else:
+ console.print(f"[green]Reconciled spend for {tag}[/]")
+ console.print(f" {data['spend']} status: {data['status']}")
+
+
@app.command("event")
def run_event(
vault_tag: str = typer.Argument(..., help="Run tag"),
diff --git a/src/hyperresearch/core/runs.py b/src/hyperresearch/core/runs.py
index 19657cb..420f0b3 100644
--- a/src/hyperresearch/core/runs.py
+++ b/src/hyperresearch/core/runs.py
@@ -23,6 +23,7 @@ vault. Final reports ship to `research/notes/final_report_<vault_tag>.md`.
from __future__ import annotations
import json
+import sqlite3
from datetime import UTC, datetime
from pathlib import Path
@@ -72,6 +73,14 @@ CHAPTER_LAST_STEP = "10"
# possibly-stalled by `hpr run status`.
STALL_MINUTES = 30
+# Only these blocks can be cleared by `run resume` or `run step --force`.
+# budget/verify blocks keep their existing behavior.
+_COUNT_BLOCK_REASONS = ("max_sources", "max_notes")
+
+# Cap explicit count-block clears, including `run resume`.
+_MAX_COUNT_FORCE_CLEARS = 3
+_COUNT_FIELDS = {"max_sources": "sources_fetched", "max_notes": "notes_written"}
+
class RunError(Exception):
pass
@@ -91,14 +100,24 @@ def init_run(
profile: str = "full",
budget_usd: float | None = None,
query: str | None = None,
+ max_sources: int | None = None,
+ max_notes: int | None = None,
) -> dict:
"""Scaffold research/runs/<vault_tag>/ and write a fresh manifest.
Idempotent: re-running on an existing run returns the existing manifest
unchanged (so a recovering orchestrator can call it safely).
+
+ ``max_sources`` / ``max_notes`` are optional observable ceilings checked
+ at step-done against vault_tag-filtered counts (not mtime).
"""
from hyperresearch.core.profiles import resolve_profile
+ if max_sources is not None and max_sources <= 0:
+ raise RunError("--max-sources must be a positive integer")
+ if max_notes is not None and max_notes <= 0:
+ raise RunError("--max-notes must be a positive integer")
+
run_dir = vault.run_dir(vault_tag)
mpath = run_dir / MANIFEST_NAME
if mpath.exists():
@@ -112,15 +131,20 @@ def init_run(
if query is not None:
(run_dir / "query.md").write_text(query, encoding="utf-8")
+ now = _now()
manifest = {
"manifest_version": MANIFEST_VERSION,
"vault_tag": vault_tag,
"profile": profile,
"profile_steps": [str(s) for s in resolved.steps],
"status": "running",
- "started_at": _now(),
- "updated_at": _now(),
+ "started_at": now,
+ "updated_at": now,
"budget_usd": budget_usd,
+ "max_sources": max_sources,
+ "max_notes": max_notes,
+ "counts_force_cleared": 0,
+ "counts_clear_baselines": {}, # reason -> count when last cleared
"blocked_on": None,
"steps": {},
"chapters": {},
@@ -154,7 +178,7 @@ def _save(vault, vault_tag: str, manifest: dict) -> None:
def record_event(vault, vault_tag: str, event: dict) -> None:
- """Append one event to events.jsonl and touch the manifest heartbeat.
+ """Append one event to events.jsonl and touch updated_at for stall detection.
A `chapter-plan` event (step 1.5) also registers its chapter in
`manifest["chapters"]` — status "planned", plus the title when given —
@@ -171,7 +195,7 @@ def record_event(vault, vault_tag: str, event: dict) -> None:
manifest = load_manifest(vault, vault_tag)
if event.get("type") == CHAPTER_PLAN_EVENT:
_fold_chapter_plan(manifest, event)
- _save(vault, vault_tag, manifest) # heartbeat
+ _save(vault, vault_tag, manifest) # touch updated_at for stall detection
# Bounds on what a chapter-plan event may write into the manifest. Events
@@ -219,11 +243,32 @@ def set_step(
step: str,
status: str,
chapter: str | None = None,
+ force: bool = False,
) -> dict:
- """Mark a step's status. Steps are keyed as strings ("1", "1.5", "11g")."""
+ """Mark a step's status. Steps are keyed as strings ("1", "1.5", "11g").
+
+ On ``done``, reconciles vault_tag-filtered counts and applies max_sources /
+ max_notes. A count block requires a force-clear (up to the cap) before
+ recording the step; budget/verify blocks cannot be cleared with force.
+ """
if status not in STEP_STATUSES:
raise RunError(f"invalid step status '{status}' (one of {STEP_STATUSES})")
manifest = load_manifest(vault, vault_tag)
+ blocked_on = manifest.get("blocked_on") if manifest.get("status") == "blocked" else None
+
+ if status == "done" and blocked_on is not None:
+ if blocked_on in _COUNT_BLOCK_REASONS and not force:
+ raise RunError(
+ f"run '{vault_tag}' is blocked on {blocked_on!r}; "
+ "resolve the limit or re-run step done with --force"
+ )
+ if blocked_on not in _COUNT_BLOCK_REASONS:
+ raise RunError(
+ f"run '{vault_tag}' is blocked on {blocked_on!r}; "
+ "this block cannot be cleared with --force"
+ )
+ manifest = clear_count_block(vault, vault_tag)
+
entry = manifest["steps"].setdefault(str(step), {})
entry["status"] = status
if status == "running" and "started_at" not in entry:
@@ -235,7 +280,21 @@ def set_step(
ch = manifest["chapters"].setdefault(chapter, {})
ch["status"] = f"step-{step}-{status}"
_save(vault, vault_tag, manifest)
- record_event(vault, vault_tag, {"type": "step", "step": str(step), "status": status, "chapter": chapter})
+ record_event(
+ vault,
+ vault_tag,
+ {
+ "type": "step",
+ "step": str(step),
+ "status": status,
+ "chapter": chapter,
+ "force": bool(force),
+ },
+ )
+ # Agents rarely call `hpr run spend`; reconciling at step boundaries is
+ # what lets count ceilings fire mid-run instead of only at `run finish` (#92).
+ if status == "done":
+ manifest = reconcile_spend_from_disk(vault, vault_tag)
return manifest
@@ -265,6 +324,114 @@ def add_spend(
return manifest
+def _count_notes_and_sources(vault, vault_tag: str) -> tuple[int, int]:
+ """Count tagged notes and distinct fetched source URLs linked to them.
+
+ Concurrent runs share the vault and note update / repair / sources score
+ rewrite files, so mtime is not a valid run filter. HTML and PDF fetches
+ both create rows in the sources table.
+ """
+ tag = (vault_tag or "").strip().lower()
+ conn = vault.db
+ try:
+ notes = conn.execute(
+ """
+ SELECT COUNT(*) FROM notes n
+ JOIN tags t ON t.note_id = n.id
+ WHERE t.tag = ?
+ """,
+ (tag,),
+ ).fetchone()[0]
+ sources = conn.execute(
+ """
+ SELECT COUNT(DISTINCT s.url) FROM sources s
+ JOIN tags t ON t.note_id = s.note_id
+ WHERE t.tag = ?
+ """,
+ (tag,),
+ ).fetchone()[0]
+ except sqlite3.Error as e:
+ # Do not invent zero counts — that is the #92 failure mode.
+ raise RunError(f"failed to count notes or sources for '{vault_tag}': {e}") from e
+ return notes, sources
+
+
+def clear_count_block(vault, vault_tag: str) -> dict:
+ """Clear one count block until its observed count increases again."""
+ manifest = load_manifest(vault, vault_tag)
+ reason = manifest.get("blocked_on")
+ if manifest.get("status") != "blocked" or reason not in _COUNT_BLOCK_REASONS:
+ raise RunError(f"run '{vault_tag}' has no count block to clear")
+ cleared = int(manifest.get("counts_force_cleared", 0) or 0)
+ if cleared >= _MAX_COUNT_FORCE_CLEARS:
+ raise RunError(f"run '{vault_tag}' reached the count force-clear limit")
+ # Refresh the snapshot before clearing; a fetch may have landed since
+ # the step that created the block.
+ manifest = reconcile_spend_from_disk(vault, vault_tag)
+ baselines = manifest.setdefault("counts_clear_baselines", {})
+ baselines[reason] = int(manifest["spend"].get(_COUNT_FIELDS[reason], 0) or 0)
+ manifest["counts_force_cleared"] = cleared + 1
+ manifest["status"] = "running"
+ manifest["blocked_on"] = None
+ _save(vault, vault_tag, manifest)
+ record_event(vault, vault_tag, {"type": "counts_force_clear", "cleared": cleared + 1})
+ return load_manifest(vault, vault_tag)
+
+
+def _apply_count_ceilings(manifest: dict) -> None:
+ """Flip to blocked when max_sources / max_notes are crossed (running only)."""
+ if manifest.get("status") != "running":
+ return
+ spend = manifest.get("spend", {})
+ max_sources = manifest.get("max_sources")
+ max_notes = manifest.get("max_notes")
+ baselines = manifest.get("counts_clear_baselines", {})
+ for reason, ceiling in (("max_sources", max_sources), ("max_notes", max_notes)):
+ count = int(spend.get(_COUNT_FIELDS[reason], 0) or 0)
+ baseline = baselines.get(reason)
+ if ceiling is not None and count >= ceiling and (baseline is None or count > baseline):
+ manifest["status"] = "blocked"
+ manifest["blocked_on"] = reason
+ baselines.pop(reason, None)
+ return
+
+
+def reconcile_spend_from_disk(vault, vault_tag: str) -> dict:
+ """Fold vault_tag-filtered notes and fetched URLs into spend.
+
+ Pipeline agents often never call `hpr run spend` (#92). Counts come from
+ the vault DB (tag + sources), not mtime. Agent-reported estimated_usd is
+ left alone — this repo does not carry unit prices.
+ """
+ manifest = load_manifest(vault, vault_tag)
+
+ notes, sources = _count_notes_and_sources(vault, vault_tag)
+
+ spend = manifest.setdefault("spend", {})
+ spend["sources_fetched"] = sources
+ spend["notes_written"] = notes
+ # estimated_usd and agents_spawned only move via add_spend / hpr run spend.
+
+ _apply_count_ceilings(manifest)
+
+ _save(vault, vault_tag, manifest)
+ record_event(
+ vault,
+ vault_tag,
+ {
+ "type": "spend_reconcile",
+ "sources_fetched": sources,
+ "notes_written": notes,
+ "agents_spawned": spend.get("agents_spawned", 0),
+ "estimated_usd": spend.get("estimated_usd", 0.0),
+ "max_sources": manifest.get("max_sources"),
+ "max_notes": manifest.get("max_notes"),
+ "blocked_on": manifest.get("blocked_on"),
+ },
+ )
+ return manifest
+
+
def set_status(vault, vault_tag: str, status: str, blocked_on: str | None = None) -> dict:
if status not in RUN_STATUSES:
raise RunError(f"invalid run status '{status}' (one of {RUN_STATUSES})")
@@ -688,6 +855,9 @@ def finish_run(vault, vault_tag: str) -> dict:
earned it.
"""
result = verify_run(vault, vault_tag)
+ # Counts come from vault_tag-filtered disk/DB so a finished run never
+ # reports zero just because agents skipped `hpr run spend`.
+ reconcile_spend_from_disk(vault, vault_tag)
manifest = load_manifest(vault, vault_tag)
manifest["verify"] = {
"passed": result["passed"],
diff --git a/tests/test_core/test_runs.py b/tests/test_core/test_runs.py
index 5ac2cea..eefbc7d 100644
--- a/tests/test_core/test_runs.py
+++ b/tests/test_core/test_runs.py
@@ -13,6 +13,7 @@ from hyperresearch.core.runs import (
init_run,
list_runs,
load_manifest,
+ reconcile_spend_from_disk,
resume_position,
run_resume_position,
set_step,
@@ -117,6 +118,203 @@ class TestStepsAndResume:
assert any(json.loads(ln)["type"] == "step" for ln in lines)
+def _write_tagged_note(vault, note_id: str, vault_tag: str, raw_file: str | None = None) -> None:
+ """Write a notes/*.md with vault_tag (and optional raw_file) and sync."""
+ notes = vault.notes_dir
+ notes.mkdir(parents=True, exist_ok=True)
+ fm = [f"id: {note_id}", f"title: {note_id}", f"tags: [{vault_tag}]"]
+ if raw_file:
+ fm.append(f"raw_file: {raw_file}")
+ (notes / f"{note_id}.md").write_text(
+ "---\n" + "\n".join(fm) + "\n---\n\nbody\n",
+ encoding="utf-8",
+ )
+ from hyperresearch.core.sync import compute_sync_plan, execute_sync
+
+ execute_sync(vault, compute_sync_plan(vault, force=True))
+
+
+def _add_source(vault, note_id: str, url: str) -> None:
+ with vault.db as conn:
+ conn.execute("INSERT INTO sources (url, note_id) VALUES (?, ?)", (url, note_id))
+
+
+class TestReconcileSpend:
+ def test_reconcile_counts_fetched_urls_by_tag(self, tmp_vault):
+ init_run(tmp_vault, "r-000001", budget_usd=1.0)
+ raw = tmp_vault.research_dir / "raw"
+ raw.mkdir(parents=True, exist_ok=True)
+ (raw / "paper.pdf").write_bytes(b"%PDF-1.4")
+ for i in range(5):
+ note_id = f"html-{i}"
+ _write_tagged_note(tmp_vault, note_id, "r-000001")
+ _add_source(tmp_vault, note_id, f"https://example.com/{i}")
+ _write_tagged_note(tmp_vault, "paper", "r-000001", raw_file="raw/paper.pdf")
+ _add_source(tmp_vault, "paper", "https://example.com/paper.pdf")
+ _write_tagged_note(tmp_vault, "other", "other-run")
+ _add_source(tmp_vault, "other", "https://example.com/other")
+
+ m = reconcile_spend_from_disk(tmp_vault, "r-000001")
+ assert m["spend"]["notes_written"] == 6
+ assert m["spend"]["sources_fetched"] == 6
+ # No unit prices in this repo — estimated_usd only moves via add_spend.
+ assert m["spend"]["estimated_usd"] == 0.0
+ assert m["status"] == "running"
+
+ def test_reconcile_keeps_agent_estimate(self, tmp_vault):
+ init_run(tmp_vault, "r-000003")
+ add_spend(tmp_vault, "r-000003", estimated_usd=12.5, agents_spawned=2)
+ for _ in range(3):
+ runs_mod.record_event(tmp_vault, "r-000003", {"type": "agent_spawn"})
+ m = reconcile_spend_from_disk(tmp_vault, "r-000003")
+ assert m["spend"]["estimated_usd"] == 12.5
+ assert m["spend"]["agents_spawned"] == 2
+
+ def test_init_stores_count_ceilings(self, tmp_vault):
+ m = init_run(tmp_vault, "r-000004", max_sources=10, max_notes=20)
+ assert m["max_sources"] == 10
+ assert m["max_notes"] == 20
+ assert m.get("pid") is None
+ assert m.get("heartbeat_at") is None
+
+ def test_max_notes_blocks_on_step_done(self, tmp_vault):
+ init_run(tmp_vault, "r-000005", max_notes=1)
+ _write_tagged_note(tmp_vault, "n1", "r-000005")
+ _write_tagged_note(tmp_vault, "n2", "r-000005")
+ m = set_step(tmp_vault, "r-000005", "1", "done")
+ assert m["status"] == "blocked"
+ assert m["blocked_on"] == "max_notes"
+
+ def test_max_sources_blocks_on_step_done(self, tmp_vault):
+ init_run(tmp_vault, "r-000006", max_sources=1)
+ _write_tagged_note(tmp_vault, "s1", "r-000006")
+ _write_tagged_note(tmp_vault, "s2", "r-000006")
+ _add_source(tmp_vault, "s1", "https://example.com/a")
+ _add_source(tmp_vault, "s2", "https://example.com/b")
+ m = set_step(tmp_vault, "r-000006", "1", "done")
+ assert m["status"] == "blocked"
+ assert m["blocked_on"] == "max_sources"
+
+ def test_blocked_done_requires_force(self, tmp_vault):
+ init_run(tmp_vault, "r-000007", max_notes=1)
+ _write_tagged_note(tmp_vault, "x1", "r-000007")
+ _write_tagged_note(tmp_vault, "x2", "r-000007")
+ set_step(tmp_vault, "r-000007", "1", "done")
+ with pytest.raises(RunError, match="blocked"):
+ set_step(tmp_vault, "r-000007", "2", "done")
+
+ def test_force_does_not_clear_budget_block(self, tmp_vault):
+ init_run(tmp_vault, "r-000009", budget_usd=5.0)
+ add_spend(tmp_vault, "r-000009", estimated_usd=10.0)
+ assert load_manifest(tmp_vault, "r-000009")["blocked_on"] == "budget"
+ with pytest.raises(RunError, match="cannot be cleared with --force"):
+ set_step(tmp_vault, "r-000009", "1", "done", force=True)
+ m = load_manifest(tmp_vault, "r-000009")
+ assert m["status"] == "blocked"
+ assert m["blocked_on"] == "budget"
+
+ def test_force_clears_block_so_resume_progresses(self, tmp_vault):
+ init_run(tmp_vault, "r-000008", max_notes=1)
+ _write_tagged_note(tmp_vault, "y1", "r-000008")
+ _write_tagged_note(tmp_vault, "y2", "r-000008")
+ set_step(tmp_vault, "r-000008", "1", "done")
+ # Same ceiling, no new files: force must unblock and accept the next done.
+ m = set_step(tmp_vault, "r-000008", "2", "done", force=True)
+ assert m["steps"]["2"]["status"] == "done"
+ assert m["counts_force_cleared"] == 1
+ assert m["status"] == "running"
+ # Unchanged counts stay clear across subsequent steps.
+ m_same = set_step(tmp_vault, "r-000008", "10", "done")
+ assert m_same["status"] == "running"
+ _write_tagged_note(tmp_vault, "y3", "r-000008")
+ m_reblock = set_step(tmp_vault, "r-000008", "15", "done")
+ assert m_reblock["status"] == "blocked"
+ m2 = set_step(tmp_vault, "r-000008", "16", "done", force=True)
+ assert m2["steps"]["16"]["status"] == "done"
+ assert m2["counts_force_cleared"] == 2
+
+ def test_force_clear_cap_rejects_step_before_recording_it(self, tmp_vault):
+ init_run(tmp_vault, "r-000010", max_notes=1)
+ for i in range(3):
+ _write_tagged_note(tmp_vault, f"z{i}", "r-000010")
+ set_step(tmp_vault, "r-000010", str(i * 2 + 1), "done")
+ m = set_step(tmp_vault, "r-000010", str(i * 2 + 2), "done", force=True)
+ assert m["status"] == "running"
+ assert m["counts_force_cleared"] == 3
+ _write_tagged_note(tmp_vault, "z3", "r-000010")
+ set_step(tmp_vault, "r-000010", "7", "done")
+ with pytest.raises(RunError, match="force-clear limit"):
+ set_step(tmp_vault, "r-000010", "8", "done", force=True)
+ m4 = load_manifest(tmp_vault, "r-000010")
+ assert "8" not in m4["steps"]
+ assert m4["status"] == "blocked"
+ assert m4["counts_force_cleared"] == 3
+
+ def test_resume_clear_holds_until_count_increases(self, tmp_vault, monkeypatch):
+ from typer.testing import CliRunner
+
+ from hyperresearch.cli import app
+
+ tag = "r-resume-000001"
+ init_run(tmp_vault, tag, max_notes=1)
+ _write_tagged_note(tmp_vault, "resume-1", tag)
+ set_step(tmp_vault, tag, "1", "done")
+ monkeypatch.chdir(tmp_vault.root)
+ result = CliRunner().invoke(app, ["run", "resume", tag, "--json"])
+ assert result.exit_code == 0
+ assert load_manifest(tmp_vault, tag)["counts_force_cleared"] == 1
+ assert set_step(tmp_vault, tag, "2", "done")["status"] == "running"
+ _write_tagged_note(tmp_vault, "resume-2", tag)
+ assert set_step(tmp_vault, tag, "10", "done")["blocked_on"] == "max_notes"
+
+ def test_resume_cannot_bypass_clear_cap(self, tmp_vault, monkeypatch):
+ from typer.testing import CliRunner
+
+ from hyperresearch.cli import app
+
+ tag = "r-resume-cap-000001"
+ init_run(tmp_vault, tag, max_notes=1)
+ monkeypatch.chdir(tmp_vault.root)
+ runner = CliRunner()
+ for i in range(3):
+ _write_tagged_note(tmp_vault, f"cap-{i}", tag)
+ set_step(tmp_vault, tag, str(i + 1), "done")
+ assert runner.invoke(app, ["run", "resume", tag, "--json"]).exit_code == 0
+ _write_tagged_note(tmp_vault, "cap-3", tag)
+ set_step(tmp_vault, tag, "4", "done")
+ result = runner.invoke(app, ["run", "resume", tag, "--json"])
+ assert result.exit_code == 1
+ assert "force-clear limit" in result.stdout
+ assert load_manifest(tmp_vault, tag)["status"] == "blocked"
+
+ def test_resume_count_block_honors_declared_tier(self, tmp_vault, monkeypatch):
+ from typer.testing import CliRunner
+
+ from hyperresearch.cli import app
+
+ tag = "r-resume-tier-000001"
+ init_run(tmp_vault, tag, profile="full", max_notes=1)
+ (tmp_vault.run_dir(tag) / "prompt-decomposition.json").write_text(
+ json.dumps({"pipeline_tier": "light"}), encoding="utf-8"
+ )
+ set_step(tmp_vault, tag, "1", "done")
+ _write_tagged_note(tmp_vault, "tier-note", tag)
+ assert set_step(tmp_vault, tag, "2", "done")["blocked_on"] == "max_notes"
+ monkeypatch.chdir(tmp_vault.root)
+
+ result = CliRunner().invoke(app, ["run", "resume", tag, "--json"])
+
+ assert result.exit_code == 0
+ data = json.loads(result.stdout)["data"]
+ assert data["next_step"] == "10"
+ assert data["remaining_steps"] == ["10", "15", "16"]
+ assert data["codex_step_file"].endswith(f"/{data['skill_to_invoke']}.md")
+ manifest = load_manifest(tmp_vault, tag)
+ assert manifest["counts_force_cleared"] == 1
+ assert manifest["counts_clear_baselines"]["max_notes"] == 1
+ assert set_step(tmp_vault, tag, "10", "done")["status"] == "running"
+
+
class TestBudgetGovernor:
def test_spend_accumulates(self, tmp_vault):
init_run(tmp_vault, "b-000001", budget_usd=100.0)
@@ -158,7 +356,7 @@ class TestStatusSummary:
init_run(tmp_vault, "s-000001")
summary = status_summary(tmp_vault, "s-000001")
assert summary["possibly_stalled"] is False
- # Backdate the heartbeat
+ # Backdate the last update
m = load_manifest(tmp_vault, "s-000001")
m["updated_at"] = "2020-01-01T00:00:00+00:00"
mpath = runs_mod.manifest_path(tmp_vault, "s-000001")
@@ -171,6 +369,16 @@ class TestStatusSummary:
class TestRunCli:
+ def test_reconcile_bad_tag_reports_error(self, tmp_vault, monkeypatch):
+ from typer.testing import CliRunner
+
+ from hyperresearch.cli import app
+
+ monkeypatch.chdir(tmp_vault.root)
+ result = CliRunner().invoke(app, ["run", "reconcile", "../bad", "--json"])
+ assert result.exit_code == 1
+ assert json.loads(result.stdout)["ok"] is False
+
def test_init_status_resume_roundtrip(self, tmp_vault, monkeypatch):
from typer.testing import CliRunner