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
Python agentsagentskillscitationsclaude-codecodexcodex-plugincodex-skilldeep-researchdeep-research-agentdeepresearchmcp-serverresearchresearch-agentresearch-tools
fix(runs): count fetched URLs and enforce count ceilings (#115)
Aurora92744f83fc08
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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-24diff --git a/src/hyperresearch/cli/run_cmd.py b/src/hyperresearch/cli/run_cmd.pyindex 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_stepvault = _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.pyindex 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 annotationsimport json+import sqlite3from datetime import UTC, datetimefrom 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 manifestunchanged (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_NAMEif 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"] = statusif 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.pyindex 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 updatem = 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