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: validate the run tag so it can only name a child of research/runs/ (#125)

Jordan Gibbs75b1ecfb2891
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c904de..57d03af 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
## [Unreleased]
+- **A run tag is a slug (#116).** `Vault.run_dir()` joined the tag onto `research/runs/` unchecked, and pathlib replaces the base on an absolute segment, so `hpr run init ../../x` or `hpr run init C:/anything` scaffolded a run workspace outside the vault and every later `run` subcommand followed it there. Tags are now validated at that one seam: letters, digits, `-`, `_` and `.`, starting with a letter or digit, which is what `hpr vault-tag` mints. `run`, `levers` and `citecheck` report a bad tag as a clean error instead of a traceback. Same bug class as the `claims ingest --tag` traversal fixed in 0.11.1; exposure is low because the tag comes from the operator or the orchestrating agent, not from fetched content.
- **The builtin provider fetches PDFs (#82, reported by @earldodd).** The PDF lane (`_is_pdf_url` / `_fetch_pdf`) lived inside the crawl4ai provider only, so a vault still on `provider = "builtin"` (the default until `hpr install` switches it) had no PDF handling at all: a direct `.pdf` link was decoded as HTML text and rejected by the junk gate as "Binary PDF garbage in content", identically for every mirror of the same document, and an arXiv `/abs/` link saved the 900-word abstract page instead of the paper. The lane now lives in `web/pdf.py` and both providers use it; the crawl4ai module keeps the old names. The builtin provider also detects a PDF from its bytes when the URL does not look like one. When the PDF lane declines a URL and the HTML fallback turns out to be junk, `hpr fetch -j` now says why the lane declined it (`PDF lane: HTTP 403`, `no extractable text layer`, ...) instead of the generic junk verdict, and the pymupdf document handle is closed on the exception path instead of leaking one per encrypted PDF.
- **`serply` web provider.** Google organic results with page fetch through the same `SERPLY_API_KEY`; opt-in via `[web] provider = "serply"`, no new dependency.
diff --git a/src/hyperresearch/cli/citecheck_cmd.py b/src/hyperresearch/cli/citecheck_cmd.py
index 1955b70..a2bb0ee 100644
--- a/src/hyperresearch/cli/citecheck_cmd.py
+++ b/src/hyperresearch/cli/citecheck_cmd.py
@@ -26,7 +26,7 @@ def citecheck_extract(
runs/<tag>/cite-check-pairs.json for the cite-checker agent.
"""
from hyperresearch.core.citecheck import write_pairs_file
- from hyperresearch.core.vault import Vault, VaultError
+ from hyperresearch.core.vault import InvalidRunTagError, Vault, VaultError, validate_run_tag
try:
vault = Vault.discover()
@@ -37,6 +37,15 @@ def citecheck_extract(
console.print(f"[red]Error:[/] {e}")
raise typer.Exit(1)
+ try:
+ validate_run_tag(vault_tag)
+ except InvalidRunTagError as e:
+ if json_output:
+ output(error(str(e), "INVALID_TAG"), json_mode=True)
+ else:
+ console.print(f"[red]Error:[/] {e}")
+ raise typer.Exit(1)
+
vault.auto_sync()
report_path = Path(report) if report else (
vault.root / "research" / "notes" / f"final_report_{vault_tag}.md"
diff --git a/src/hyperresearch/cli/levers_cmd.py b/src/hyperresearch/cli/levers_cmd.py
index d9936b9..d774b75 100644
--- a/src/hyperresearch/cli/levers_cmd.py
+++ b/src/hyperresearch/cli/levers_cmd.py
@@ -5,13 +5,14 @@ from __future__ import annotations
import typer
from hyperresearch.cli._output import console, output
+from hyperresearch.core.vault import VaultError
from hyperresearch.models.output import error, success
app = typer.Typer()
def _discover(json_output: bool):
- from hyperresearch.core.vault import Vault, VaultError
+ from hyperresearch.core.vault import Vault
try:
return Vault.discover()
@@ -49,7 +50,7 @@ def levers_render(
vault.auto_sync()
try:
result = render_shims(vault, vault_tag)
- except LeverError as e:
+ except (LeverError, VaultError) as e:
_fail(str(e), "LEVER_ERROR", json_output)
return
levers = result["levers"]
@@ -91,7 +92,7 @@ def levers_set(
result = {"levers": levers, "rerendered": rerender}
if rerender:
result = {**render_shims(vault, vault_tag), "rerendered": True}
- except LeverError as e:
+ except (LeverError, VaultError) as e:
_fail(str(e), "LEVER_ERROR", json_output)
return
if json_output:
diff --git a/src/hyperresearch/cli/run_cmd.py b/src/hyperresearch/cli/run_cmd.py
index d5c02be..07e8d5a 100644
--- a/src/hyperresearch/cli/run_cmd.py
+++ b/src/hyperresearch/cli/run_cmd.py
@@ -7,13 +7,14 @@ import json
import typer
from hyperresearch.cli._output import console, output
+from hyperresearch.core.vault import VaultError
from hyperresearch.models.output import error, success
app = typer.Typer()
def _vault_or_exit(json_output: bool):
- from hyperresearch.core.vault import Vault, VaultError
+ from hyperresearch.core.vault import Vault
try:
return Vault.discover()
@@ -59,7 +60,7 @@ def run_init(
query = Path(query_file).read_text(encoding="utf-8-sig")
try:
manifest = init_run(vault, vault_tag, profile=profile, budget_usd=budget, query=query)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -86,7 +87,7 @@ def run_status(
tag = _resolve_tag(vault, vault_tag, json_output)
try:
summary = status_summary(vault, tag)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -168,7 +169,7 @@ def run_resume(
tag = _resolve_tag(vault, vault_tag, json_output)
try:
manifest = load_manifest(vault, tag)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -210,7 +211,7 @@ def run_abort(
vault = _vault_or_exit(json_output)
try:
manifest = set_status(vault, vault_tag, "aborted")
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -236,7 +237,7 @@ def run_step(
vault = _vault_or_exit(json_output)
try:
manifest = set_step(vault, vault_tag, step, status, chapter=chapter)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -267,7 +268,7 @@ def run_spend(
estimated_usd=usd, sources_fetched=sources,
notes_written=notes, agents_spawned=agents,
)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -303,7 +304,7 @@ def run_event(
raise typer.Exit(1)
try:
record_event(vault, vault_tag, payload)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -327,7 +328,7 @@ def run_block(
vault = _vault_or_exit(json_output)
try:
manifest = set_status(vault, vault_tag, "blocked", blocked_on=on)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -362,7 +363,7 @@ def run_report(
continue
try:
reports.append(run_report_data(vault, tag))
- except RunError:
+ except (RunError, VaultError):
continue
agg = {
"runs": len(reports),
@@ -385,7 +386,7 @@ def run_report(
try:
load_manifest(vault, tag)
report = run_report_data(vault, tag)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -424,7 +425,7 @@ def run_verify(
tag = _resolve_tag(vault, vault_tag, json_output)
try:
result = verify_run(vault, tag)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
@@ -460,7 +461,7 @@ def run_finish(
tag = _resolve_tag(vault, vault_tag, json_output)
try:
result = finish_run(vault, tag)
- except RunError as e:
+ except (RunError, VaultError) as e:
if json_output:
output(error(str(e), "RUN_ERROR"), json_mode=True)
else:
diff --git a/src/hyperresearch/core/vault.py b/src/hyperresearch/core/vault.py
index 982b78e..15d45f5 100644
--- a/src/hyperresearch/core/vault.py
+++ b/src/hyperresearch/core/vault.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+import re
import sqlite3
from pathlib import Path
@@ -17,6 +18,33 @@ class VaultError(Exception):
pass
+class InvalidRunTagError(VaultError):
+ """A run tag that is not a plain slug (path separators, `..`, absolute paths)."""
+
+
+# A run tag is a slug: what `hpr vault-tag` mints, plus underscore and dot so
+# hand-written tags survive. No separators, so it can only ever name a child
+# of research/runs/; the leading character rule rejects `.` and `..`.
+RUN_TAG_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$")
+
+
+def validate_run_tag(vault_tag: str) -> str:
+ """Return the tag unchanged, or raise InvalidRunTagError.
+
+ Every run command joins the tag onto research/runs/, and pathlib replaces
+ the base on an absolute segment, so without this `run init ../../x` or
+ `run init C:/anything` scaffolds a workspace outside the vault and every
+ later subcommand follows it there (#116).
+ """
+ if not isinstance(vault_tag, str) or not RUN_TAG_RE.fullmatch(vault_tag):
+ raise InvalidRunTagError(
+ f"invalid run tag {vault_tag!r}: a tag is a slug of letters, digits, "
+ "'-', '_' and '.', starting with a letter or digit (mint one with "
+ "`hyperresearch vault-tag <slug>`)"
+ )
+ return vault_tag
+
+
class Vault:
"""Represents a hyperresearch research base vault."""
@@ -85,7 +113,7 @@ class Vault:
return self.research_dir / "runs"
def run_dir(self, vault_tag: str) -> Path:
- return self.runs_dir / vault_tag
+ return self.runs_dir / validate_run_tag(vault_tag)
@property
def templates_dir(self) -> Path:
diff --git a/tests/test_core/test_run_tag_validation.py b/tests/test_core/test_run_tag_validation.py
new file mode 100644
index 0000000..10f28b9
--- /dev/null
+++ b/tests/test_core/test_run_tag_validation.py
@@ -0,0 +1,115 @@
+"""A run tag is a slug; it can only ever name a child of research/runs/ (#116).
+
+`Vault.run_dir()` joins the tag onto research/runs/ and pathlib replaces the
+base on an absolute segment, so before this `run init ../../x` (or an
+absolute path) scaffolded a run workspace outside the vault and every later
+`run` subcommand followed it there. Same bug class as the `claims ingest
+--tag` traversal fixed in #114; this one is closed at the single seam every
+run command goes through.
+"""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+from typer.testing import CliRunner
+
+from hyperresearch.cli import app
+from hyperresearch.core.vault import InvalidRunTagError, validate_run_tag
+
+runner = CliRunner()
+
+
+ "tag",
+ [
+ "efield-dft-sac-3f9a1c",
+ "non-ai-web-design-trends-2026-b0dbbe",
+ "Run_2026.09.12",
+ "a",
+ "x" * 100,
+ ],
+)
+def test_slugs_pass(tag):
+ assert validate_run_tag(tag) == tag
+
+
+ "tag",
+ [
+ "../../x",
+ "..",
+ ".",
+ ".hidden",
+ "-leading-dash",
+ "a/b",
+ "a\b",
+ "C:/anything",
+ "/etc/passwd",
+ "has space",
+ "",
+ "x" * 101,
+ "tag\n",
+ ],
+)
+def test_paths_and_junk_are_refused(tag):
+ with pytest.raises(InvalidRunTagError):
+ validate_run_tag(tag)
+
+
+def test_run_dir_refuses_before_touching_the_filesystem(tmp_vault):
+ with pytest.raises(InvalidRunTagError):
+ tmp_vault.run_dir("../../escape")
+ assert not (tmp_vault.root.parent / "escape").exists()
+
+
+def test_run_init_with_a_traversal_tag_is_a_clean_error(tmp_vault, monkeypatch):
+ monkeypatch.chdir(tmp_vault.root)
+ outside = tmp_vault.root.parent / "outside"
+
+ result = runner.invoke(app, ["run", "init", "../../outside", "-j"])
+
+ payload = json.loads(result.stdout)
+ assert result.exit_code == 1
+ assert payload["ok"] is False
+ assert "invalid run tag" in payload["error"]
+ assert not outside.exists()
+ assert not (tmp_vault.root / "research" / "runs").exists() or not any(
+ (tmp_vault.root / "research" / "runs").iterdir()
+ )
+
+
+def test_run_init_with_an_absolute_tag_is_a_clean_error(tmp_vault, tmp_path, monkeypatch):
+ monkeypatch.chdir(tmp_vault.root)
+ target = tmp_path / "elsewhere"
+
+ result = runner.invoke(app, ["run", "init", str(target), "-j"])
+
+ assert result.exit_code == 1
+ assert json.loads(result.stdout)["ok"] is False
+ assert not target.exists()
+
+
+def test_other_run_commands_report_the_bad_tag_too(tmp_vault, monkeypatch):
+ monkeypatch.chdir(tmp_vault.root)
+ for argv in (
+ ["run", "status", "../../x", "-j"],
+ ["run", "step", "../../x", "1", "--status", "done", "-j"],
+ ["run", "verify", "../../x", "-j"],
+ ["citecheck", "extract", "../../x", "-j"],
+ ["levers", "render", "../../x", "-j"],
+ ):
+ result = runner.invoke(app, argv)
+ assert result.exit_code == 1, argv
+ assert json.loads(result.stdout)["ok"] is False, argv
+ assert "invalid run tag" in json.loads(result.stdout)["error"], argv
+
+
+def test_a_good_tag_still_scaffolds_inside_the_vault(tmp_vault, monkeypatch):
+ monkeypatch.chdir(tmp_vault.root)
+
+ result = runner.invoke(app, ["run", "init", "good-tag-0a1b2c", "-j"])
+
+ assert result.exit_code == 0, result.stdout
+ assert (tmp_vault.root / "research" / "runs" / "good-tag-0a1b2c" / "run.json").exists()