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
v0.8.6: run-to-run safety — sync collision fix (#25), archive-run, vault-tag (#28)
Jordan Gibbsbca1c45fd09e
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 18e1705..65c80b7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,17 @@# Changelog+## [0.8.6] - 2026-05-14++### Run-to-run safety: no more silent overwrites between /hyperresearch sessions++Three changes that close the remaining "I ran another hyperresearch and lost stuff" foot-guns, so you can fire off runs back-to-back without thinking about it.++- **sync no longer ingests frontmatterless scratch files (closes #25).** The depth-investigator and other agents leave plain-markdown body files under `research/temp/` after calling `note new --body-file`. Those scratch files derived the same id from their stem as the canonical notes created from them, and the UPSERT race smashed the canonical row's `path` field — silently breaking subsequent `note update --add-tag` calls. `compute_sync_plan` now peeks the first 16 bytes and skips anything that doesn't open with a YAML frontmatter delimiter. Real notes (including `graph stub` sidelined notes under `research/temp/`) always have frontmatter, so the fix is content-based and doesn't break that workflow. Belt-and-suspenders: `execute_sync` now refuses to UPSERT a note whose id is already owned by a different path, surfacing collisions to `result.errors` instead of overwriting.+- **`hyperresearch archive-run` preserves prior-run artifacts.** A second `/hyperresearch` in the same vault used to silently overwrite `research/scaffold.md`, `prompt-decomposition.json`, `loci.json`, `comparisons.md`, all 4 `critic-findings-*.json`, `patch-log.json`, `polish-log.json`, `readability-*.json`, `corpus-critic-gaps.json`, plus the entire `research/temp/` scratch tree. The new command moves all of that into `research/runs/archive-<prev-tag>-<UTC-timestamp>/` before the next run starts. Cheap no-op on a fresh vault. Wired into the entry-skill bootstrap as step 0.5, so users don't have to remember to call it.+- **`hyperresearch vault-tag <slug>` mints a collision-safe vault_tag.** The orchestrator's topical slug (e.g. `efield-dft-sac`) is no longer used as the final vault_tag — `hyperresearch vault-tag` appends a random 6-hex-char suffix verified unique against every prior run's `query-*.md` and `final_report_*.md` in the live vault. Re-running the same query produces a fresh tag, so prior final reports can never be overwritten. Two queries that happen to slug-collide on shared lexical material also get distinct tags. Legacy without-suffix tags from older runs can't collide with the new format by construction.++**Limitation worth knowing:** these three changes solve sequential runs comprehensively. Two `/hyperresearch` invocations that *overlap in time* still race on the new files they both write to flat paths (scaffold.md, loci.json, etc.). True parallel-run safety needs per-run files to live under `research/runs/<vault_tag>/`, which is a deeper refactor — flagged but deferred.+## [0.8.5] - 2026-04-29### Reports self-title; wikilinks become the default citation systemdiff --git a/pyproject.toml b/pyproject.tomlindex 665b764..9d5e46d 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -4,7 +4,7 @@ build-backend = "hatchling.build"[project]name = "hyperresearch"-version = "0.8.5"+version = "0.8.6"description = "Claude Code harness for disciplined, adversarially-audited deep research with full provenance."readme = "README.md"license = "MIT"diff --git a/src/hyperresearch/cli/__init__.py b/src/hyperresearch/cli/__init__.pyindex d0bf4bf..9187726 100644--- a/src/hyperresearch/cli/__init__.py+++ b/src/hyperresearch/cli/__init__.py@@ -57,6 +57,7 @@ def main(# Root-level commands+from hyperresearch.cli.archive import archive_run as _archive_runfrom hyperresearch.cli.dedup import dedup as _dedupfrom hyperresearch.cli.fetch import fetch as _fetchfrom hyperresearch.cli.import_cmd import import_vault as _import@@ -71,6 +72,7 @@ from hyperresearch.cli.research import research as _researchfrom hyperresearch.cli.search import search as _searchfrom hyperresearch.cli.serve import serve as _servefrom hyperresearch.cli.tag import tag_list as _tags+from hyperresearch.cli.vault_tag import vault_tag as _vault_tagfrom hyperresearch.cli.watch import watch as _watchapp.command("install")(_install)@@ -91,6 +93,8 @@ app.command("research")(_research)app.command("tags")(_tags)app.command("show", hidden=True)(_show)app.command("dedup")(_dedup)+app.command("archive-run")(_archive_run)+app.command("vault-tag")(_vault_tag)app.command("import")(_import)app.command("repair")(_repair)app.command("watch")(_watch)diff --git a/src/hyperresearch/cli/archive.py b/src/hyperresearch/cli/archive.pynew file mode 100644index 0000000..b87ed67--- /dev/null+++ b/src/hyperresearch/cli/archive.py@@ -0,0 +1,182 @@+"""archive-run: move prior per-run artifacts so the next run starts clean.++When `/hyperresearch` runs a second time in the same vault, it overwrites the+unnamespaced scaffold / loci / comparisons / critic-findings / patch-log /+polish-log / prompt-decomposition + the entire research/temp/ scratch tree.+Final reports and canonical query files are namespaced by vault_tag and stay+in place; everything else gets clobbered. This command preserves the prior+run's artifacts before the next run's bootstrap writes over them.++Limitations: this protects sequential runs. Two `/hyperresearch` invocations+that overlap in time still race on the new files they both write.+"""++from __future__ import annotations++import re+import shutil+from datetime import UTC, datetime+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success++# Per-run artifacts the orchestrator and step skills write at research/ root.+# Final reports (final_report_<tag>.md) and queries (query-<tag>.md) are+# already namespaced and stay in place.+_ROOT_ARTIFACTS: tuple[str, ...] = (+ "scaffold.md",+ "prompt-decomposition.json",+ "wrapper_contract.json",+ "loci.json",+ "loci-a.json",+ "loci-b.json",+ "comparisons.md",+ "corpus-critic-gaps.json",+ "critic-findings-dialectic.json",+ "critic-findings-depth.json",+ "critic-findings-width.json",+ "critic-findings-instruction.json",+ "patch-log.json",+ "polish-log.json",+ "readability-recommendations.json",+ "readability-decisions.json",+ "audit_findings.json",+ "orchestrator-restructure-log.md",+)++# Whole-tree per-run scratch.+_SUBDIRS: tuple[str, ...] = ("temp",)++_QUERY_RE = re.compile(r"^query-(.+)\.md$")+_VAULT_TAG_RE = re.compile(+ r"vault[_\- ]?tag[:\s=]+`?([a-z0-9][a-z0-9-]*)`?", re.IGNORECASE+)+++def _infer_previous_vault_tag(research_dir: Path) -> str | None:+ """Look up the most recently-touched query-*.md and return its slug.+ Fall back to grepping scaffold.md if no query files exist.+ """+ candidates = sorted(+ research_dir.glob("query-*.md"),+ key=lambda p: p.stat().st_mtime,+ reverse=True,+ )+ for c in candidates:+ m = _QUERY_RE.match(c.name)+ if m:+ return m.group(1)+ scaffold = research_dir / "scaffold.md"+ if scaffold.exists():+ try:+ text = scaffold.read_text(encoding="utf-8", errors="replace")+ except OSError:+ return None+ m = _VAULT_TAG_RE.search(text)+ if m:+ return m.group(1)+ return None+++def _unique_archive_dir(base: Path) -> Path:+ """Append `-2`, `-3`, ... until the path is free."""+ if not base.exists():+ return base+ counter = 2+ while True:+ candidate = base.with_name(f"{base.name}-{counter}")+ if not candidate.exists():+ return candidate+ counter += 1+++def archive_run(+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Archive prior per-run artifacts to research/runs/archive-*/.++ Run this BEFORE starting a new /hyperresearch session to preserve any+ in-progress or completed prior run's scaffold, loci, comparisons,+ critic findings, patch/polish logs, and the entire research/temp/+ scratch tree. Without this step, the next run silently overwrites them.++ Final reports (research/notes/final_report_<tag>.md) and canonical query+ files (research/query-<tag>.md) are already namespaced by vault_tag and+ are left in place.+ """+ from hyperresearch.core.vault import Vault, VaultError++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ research_dir = vault.research_dir+ if not research_dir.exists():+ data = {"archived": False, "files_moved": 0, "previous_vault_tag": None}+ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[dim]Nothing to archive: research/ does not exist.[/]")+ return++ to_move: list[Path] = []+ for name in _ROOT_ARTIFACTS:+ p = research_dir / name+ if p.exists() and p.is_file():+ to_move.append(p)+ for sub in _SUBDIRS:+ d = research_dir / sub+ if d.is_dir() and any(d.iterdir()):+ to_move.append(d)++ if not to_move:+ data = {"archived": False, "files_moved": 0, "previous_vault_tag": None}+ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print("[dim]No prior run artifacts found.[/]")+ return++ prev_tag = _infer_previous_vault_tag(research_dir)+ timestamp = datetime.now(UTC).strftime("%Y%m%dT%H%M%SZ")+ suffix = f"{prev_tag}-{timestamp}" if prev_tag else timestamp+ archive_dir = _unique_archive_dir(research_dir / "runs" / f"archive-{suffix}")+ archive_dir.mkdir(parents=True)++ moved: list[dict] = []+ for src in to_move:+ dest = archive_dir / src.name+ shutil.move(str(src), str(dest))+ moved.append({+ "from": src.relative_to(vault.root).as_posix(),+ "to": dest.relative_to(vault.root).as_posix(),+ })++ # Recreate the now-empty research/temp/ so subsequent skill steps don't+ # need to remember to mkdir it.+ (research_dir / "temp").mkdir(exist_ok=True)++ data = {+ "archived": True,+ "archive_dir": archive_dir.relative_to(vault.root).as_posix(),+ "files_moved": len(moved),+ "moved": moved,+ "previous_vault_tag": prev_tag,+ }+ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print(+ f"[green]Archived[/] {len(moved)} items to "+ f"{archive_dir.relative_to(vault.root).as_posix()}"+ )+ if prev_tag:+ console.print(f" previous vault_tag: [cyan]{prev_tag}[/]")diff --git a/src/hyperresearch/cli/vault_tag.py b/src/hyperresearch/cli/vault_tag.pynew file mode 100644index 0000000..6c5c122--- /dev/null+++ b/src/hyperresearch/cli/vault_tag.py@@ -0,0 +1,136 @@+"""vault-tag: mint a guaranteed-unique vault_tag for a /hyperresearch run.++The entry skill's bootstrap turns the canonical research query into a short+topical slug (e.g. `efield-dft-sac`). On its own that slug is not unique:+two different queries can slug-collide on shared lexical material, and a+re-run of the same query produces the same slug. Either case would cause+the next run's `research/query-<tag>.md` and final+`research/notes/final_report_<tag>.md` to overwrite the prior run's, since+those are the two filenames the pipeline keys off the vault_tag.++This command takes the topical slug and appends a random 6-hex-char suffix+that's verified unique against every prior run's artifacts in the live+vault (existing query-*.md and final_report_*.md). The result —+`efield-dft-sac-a3f9b7` — is collision-safe across:++ - re-runs of the same query+ - different queries that happen to slug to the same prefix+ - legacy without-suffix tags from older runs (no overlap by construction)+"""++from __future__ import annotations++import re+import secrets+from pathlib import Path++import typer++from hyperresearch.cli._output import console, output+from hyperresearch.models.output import error, success++# Topical slug: lowercase, starts with alnum, allows alnum + dashes, up to+# 60 chars. This is intentionally permissive — the orchestrator already+# produces conservative slugs, and we don't want to bounce an otherwise+# fine input on a strict regex.+_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,59}$")++_QUERY_FILE_RE = re.compile(r"^query-(.+)\.md$")+_REPORT_FILE_RE = re.compile(r"^final_report_(.+)\.md$")++_SUFFIX_BYTES = 3 # 6 hex chars → 16M-name space+_MAX_RETRIES = 100 # 16M^100 collisions before this trips — astronomical+++def _existing_tags(vault_root: Path, research_dir: Path) -> set[str]:+ """Collect every vault_tag the vault already references on disk.++ Sources:+ - `research/query-*.md` — canonical query files (one per run)+ - `research/notes/final_report_*.md` — final reports++ Archived runs under `research/runs/archive-*/` are deliberately ignored:+ those filenames embed the OLD tag, but they don't collide with NEW+ filenames because the new ones live at the research root and the+ notes dir. Including them would only narrow the suffix space for no+ benefit.+ """+ tags: set[str] = set()+ if research_dir.is_dir():+ for p in research_dir.glob("query-*.md"):+ m = _QUERY_FILE_RE.match(p.name)+ if m:+ tags.add(m.group(1))+ notes_dir = research_dir / "notes"+ if notes_dir.is_dir():+ for p in notes_dir.glob("final_report_*.md"):+ m = _REPORT_FILE_RE.match(p.name)+ if m:+ tags.add(m.group(1))+ return tags+++def vault_tag(+ slug: str = typer.Argument(+ ...,+ help=(+ "Topical slug derived from the canonical research query "+ "(e.g. 'efield-dft-sac'). Lowercase, starts with alnum, "+ "alnum + dashes, up to 60 chars."+ ),+ ),+ json_output: bool = typer.Option(False, "--json", "-j", help="JSON output"),+) -> None:+ """Mint a unique vault_tag of the form `<slug>-<6-hex>`.++ The 6-char suffix is verified against every prior run's query and+ final-report filenames in the live vault, so a fresh /hyperresearch+ invocation can never silently overwrite a prior run's outputs even+ when the topical slug repeats.+ """+ from hyperresearch.core.vault import Vault, VaultError++ if not _SLUG_RE.match(slug):+ msg = (+ f"Invalid slug '{slug}'. Must be lowercase, start with alnum, "+ "contain only alnum + dashes, up to 60 chars."+ )+ if json_output:+ output(error(msg, "INVALID_SLUG"), json_mode=True)+ else:+ console.print(f"[red]{msg}[/]")+ raise typer.Exit(1)++ try:+ vault = Vault.discover()+ except VaultError as e:+ if json_output:+ output(error(str(e), "NO_VAULT"), json_mode=True)+ else:+ console.print(f"[red]Error:[/] {e}")+ raise typer.Exit(1)++ taken = _existing_tags(vault.root, vault.research_dir)++ for _ in range(_MAX_RETRIES):+ suffix = secrets.token_hex(_SUFFIX_BYTES)+ candidate = f"{slug}-{suffix}"+ if candidate not in taken:+ data = {"vault_tag": candidate, "slug": slug, "suffix": suffix}+ if json_output:+ output(success(data, vault=str(vault.root)), json_mode=True)+ else:+ console.print(candidate)+ return++ msg = (+ f"Could not mint a unique vault_tag for slug '{slug}' after "+ f"{_MAX_RETRIES} retries. Suffix space ({_SUFFIX_BYTES * 2} hex chars) "+ "exhausted — your vault has an implausibly large number of prior runs "+ "of this exact slug. Pick a more specific slug."+ )+ if json_output:+ output(error(msg, "TAG_SPACE_EXHAUSTED"), json_mode=True)+ else:+ console.print(f"[red]{msg}[/]")+ raise typer.Exit(1)diff --git a/src/hyperresearch/core/sync.py b/src/hyperresearch/core/sync.pyindex cb9be24..ddf7082 100644--- a/src/hyperresearch/core/sync.py+++ b/src/hyperresearch/core/sync.py@@ -3,6 +3,7 @@from __future__ import annotationsimport hashlib+import reimport sqlite3import timefrom dataclasses import dataclass, field@@ -42,6 +43,31 @@ def _should_exclude(rel_path: str, exclude_parts: list[str]) -> bool:return first in exclude_parts+_FRONTMATTER_PROBE = re.compile(rb"^---[ \t]*\r?\n")+++def _has_frontmatter(path: Path) -> bool:+ """Cheap content probe — true iff the file opens with a YAML frontmatter+ delimiter (matching parse_frontmatter's regex, with optional UTF-8 BOM).++ Real notes — including stub notes under research/temp/ — always carry+ frontmatter (write_note() in core/note.py emits it unconditionally).+ Files without it are agent scratch artifacts that should never enter the+ note index (see issue #25): interim-report body files written before+ `note new --body-file`, evidence-digest.md, draft-{a,b,c}.md, and similar.+ Ingesting them produces same-id collisions with the canonical notes+ derived from them.+ """+ try:+ with path.open("rb") as f:+ head = f.read(16)+ except OSError:+ return False+ if head.startswith(b"\xef\xbb\xbf"):+ head = head[3:]+ return _FRONTMATTER_PROBE.match(head) is not None++def compute_sync_plan(vault, force: bool = False) -> SyncPlan:"""Compare disk state against DB state. Returns a plan."""plan = SyncPlan()@@ -65,6 +91,9 @@ def compute_sync_plan(vault, force: bool = False) -> SyncPlan:# research/notes/** or research/index/**.if md_file.parent == kb_dir:continue+ # Skip scratch artifacts without YAML frontmatter.+ if not _has_frontmatter(md_file):+ continuerel = md_file.relative_to(vault.root).as_posix()disk_files[rel] = md_file.stat().st_mtime@@ -109,6 +138,36 @@ def execute_sync(vault, plan: SyncPlan) -> SyncResult:changed_ids: set[str] = set()+ # Defense-in-depth (#25): refuse to silently smash an existing row's path+ # field when a second file in the same pass derives the same id, or when+ # a new file claims an id that's already in the DB at a different path.+ # The collision would otherwise be order-dependent and lose data on the+ # next `note update`.+ deleted_paths = set(plan.to_delete)+ id_to_path: dict[str, str] = {}+ for row in conn.execute("SELECT id, path FROM notes"):+ if row["path"] in deleted_paths:+ continue+ id_to_path[row["id"]] = row["path"]++ def _upsert_with_collision_check(file_path: Path) -> str | None:+ note = read_note(file_path, vault.root)+ rel = file_path.relative_to(vault.root).as_posix()+ existing = id_to_path.get(note.meta.id)+ if existing is not None and existing != rel:+ result.errors.append({+ "path": rel,+ "error": (+ f"id collision: '{note.meta.id}' already belongs to "+ f"'{existing}'. Skipped to avoid silent overwrite."+ ),+ })+ return None+ _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)+ id_to_path[note.meta.id] = rel+ changed_ids.add(note.meta.id)+ return note.meta.id+try:# Process deletesfor rel_path in plan.to_delete:@@ -124,20 +183,16 @@ def execute_sync(vault, plan: SyncPlan) -> SyncResult:# Process addsfor file_path in plan.to_add:try:- note = read_note(file_path, vault.root)- _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)- changed_ids.add(note.meta.id)- result.added += 1+ if _upsert_with_collision_check(file_path) is not None:+ result.added += 1except Exception as e:result.errors.append({"path": str(file_path), "error": str(e)})# Process updatesfor file_path in plan.to_update:try:- note = read_note(file_path, vault.root)- _upsert_note_to_db(conn, note, now_iso, file_mtime=file_path.stat().st_mtime)- changed_ids.add(note.meta.id)- result.updated += 1+ if _upsert_with_collision_check(file_path) is not None:+ result.updated += 1except Exception as e:result.errors.append({"path": str(file_path), "error": str(e)})diff --git a/src/hyperresearch/skills/hyperresearch.md b/src/hyperresearch/skills/hyperresearch.mdindex 45c3100..3b990d8 100644--- a/src/hyperresearch/skills/hyperresearch.md+++ b/src/hyperresearch/skills/hyperresearch.md@@ -80,13 +80,15 @@ Before you invoke any step skill, do this:If either command fails because the binary isn't on PATH, tell the user to run `pip install hyperresearch` first. If both files already exist, both commands no-op cheaply — safe to run unconditionally.+0.5. **Archive any prior run's artifacts.** Run `hyperresearch archive-run --json`. If a previous `/hyperresearch` session left a scaffold, loci.json, comparisons.md, critic-findings, patch-log, polish-log, prompt-decomposition, or any `research/temp/*` scratch, this moves the whole set into `research/runs/archive-<prev-tag>-<UTC-timestamp>/` so the new run starts from a clean slate without losing the prior run's audit trail. Final reports (`research/notes/final_report_<tag>.md`) and canonical query files (`research/query-<tag>.md`) are already namespaced and stay in place. The command no-ops cheaply on a fresh vault — safe to run unconditionally. **Caveat:** this protects sequential runs only. Two `/hyperresearch` invocations that overlap in time still race on the new files they both write; if you need true parallel runs, namespace per-run artifacts under `research/runs/<vault_tag>/` instead.+1. **Resolve the canonical research query.** Order of precedence:- If `research/prompt.txt` exists (legacy harness / wrapped run), read it. Its contents are the canonical research query. GOSPEL.- Otherwise, use the user's verbatim prompt as the canonical research query.- Extract wrapper requirements separately: required save path, citation format, terminal-section shape, wrapper contract. These are binding but NOT part of the query.- If `research/wrapper_contract.json` exists, read it.-2. **Generate a vault tag** (short slug from the canonical query, e.g., `efield-dft-sac`).+2. **Mint a unique vault tag.** First produce a short topical slug from the canonical query — 3–5 lowercase hyphen-separated words, e.g. `efield-dft-sac`. Then call `hyperresearch vault-tag <slug> --json` and parse the `vault_tag` field from the response. The CLI appends a random 6-hex-char suffix that's verified unique against every prior run's `research/query-*.md` and `research/notes/final_report_*.md` in this vault. The result — e.g. `efield-dft-sac-a3f9b7` — is the canonical vault_tag for the rest of the pipeline. The suffix guarantees no overwrite of a prior run's final report or query file, even if the user re-runs the exact same query or two different queries slug-collide.3. **Persist the query file.** Write the verbatim canonical query to `research/query-<vault_tag>.md`:```markdowndiff --git a/tests/test_cli/test_archive.py b/tests/test_cli/test_archive.pynew file mode 100644index 0000000..eeeeb55--- /dev/null+++ b/tests/test_cli/test_archive.py@@ -0,0 +1,161 @@+"""Tests for `hyperresearch archive-run`."""++from __future__ import annotations++import json+from pathlib import Path++import pytest+from typer.testing import CliRunner++from hyperresearch.cli import app++runner = CliRunner()+++def vault_root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ """Init a vault, chdir into it, and return its root."""+ result = runner.invoke(app, ["init", str(tmp_path / "v"), "--name", "Archive Test"])+ assert result.exit_code == 0, result.output+ root = tmp_path / "v"+ monkeypatch.chdir(root)+ return root+++def _write(path: Path, content: str = "x") -> None:+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(content, encoding="utf-8")+++def _seed_prior_run(root: Path, vault_tag: str = "alpha-beta") -> None:+ """Lay down a representative set of prior-run artifacts."""+ research = root / "research"+ # Per-run flat artifacts.+ _write(research / "scaffold.md", f"# Scaffold\n\nRun config: vault_tag: {vault_tag}\n")+ _write(research / "prompt-decomposition.json", '{"vault_tag": "' + vault_tag + '"}')+ _write(research / "loci.json", "[]")+ _write(research / "comparisons.md", "# comparisons")+ _write(research / "patch-log.json", "{}")+ _write(research / "polish-log.json", "{}")+ _write(research / "critic-findings-dialectic.json", "{}")+ # Namespaced — must NOT be archived.+ _write(research / f"query-{vault_tag}.md", "verbatim query")+ _write(research / "notes" / f"final_report_{vault_tag}.md", "---\ntitle: Report\n---\n# Report")+ # Scratch tree.+ _write(research / "temp" / "evidence-digest.md", "scratch")+ _write(research / "temp" / "claims-foo.json", "{}")+ _write(research / "temp" / "draft-a.md", "draft a")+++def test_archive_run_no_prior_artifacts_is_noop(vault_root: Path):+ """Fresh vault — archive-run reports archived=False and creates nothing."""+ result = runner.invoke(app, ["archive-run", "--json"])+ assert result.exit_code == 0, result.output+ data = json.loads(result.output)+ assert data["ok"] is True+ assert data["data"]["archived"] is False+ assert data["data"]["files_moved"] == 0+ assert not (vault_root / "research" / "runs").exists()+++def test_archive_run_moves_flat_artifacts_and_temp_tree(vault_root: Path):+ """Prior-run files and the temp/ scratch tree both end up in the archive."""+ _seed_prior_run(vault_root, vault_tag="alpha-beta")+ result = runner.invoke(app, ["archive-run", "--json"])+ assert result.exit_code == 0, result.output+ data = json.loads(result.output)+ assert data["data"]["archived"] is True+ assert data["data"]["previous_vault_tag"] == "alpha-beta"++ # Originals are gone.+ research = vault_root / "research"+ assert not (research / "scaffold.md").exists()+ assert not (research / "loci.json").exists()+ assert not (research / "comparisons.md").exists()+ assert not (research / "patch-log.json").exists()+ assert not (research / "critic-findings-dialectic.json").exists()+ assert not (research / "temp" / "evidence-digest.md").exists()+ assert not (research / "temp" / "draft-a.md").exists()++ # Namespaced files stay put.+ assert (research / "query-alpha-beta.md").exists()+ assert (research / "notes" / "final_report_alpha-beta.md").exists()++ # Archive dir holds them. Use the path the command reported.+ archive_dir = vault_root / data["data"]["archive_dir"]+ assert archive_dir.is_dir()+ assert (archive_dir / "scaffold.md").read_text(encoding="utf-8").startswith("# Scaffold")+ assert (archive_dir / "loci.json").exists()+ assert (archive_dir / "temp" / "evidence-digest.md").exists()+ assert (archive_dir / "temp" / "draft-a.md").exists()++ # research/temp/ is recreated empty so the next run can write into it+ # without an extra mkdir.+ temp = research / "temp"+ assert temp.is_dir()+ assert list(temp.iterdir()) == []++ # Archive dir name includes the inferred tag.+ assert "alpha-beta" in archive_dir.name+++def test_archive_run_falls_back_to_timestamp_when_no_tag(vault_root: Path):+ """If no query-*.md exists and scaffold.md has no recoverable vault_tag,+ the archive dir is still created (timestamp-only suffix)."""+ research = vault_root / "research"+ _write(research / "loci.json", "[]")+ _write(research / "scaffold.md", "# Scaffold\n\nno tag in here\n")+ result = runner.invoke(app, ["archive-run", "--json"])+ assert result.exit_code == 0, result.output+ data = json.loads(result.output)+ assert data["data"]["archived"] is True+ assert data["data"]["previous_vault_tag"] is None+ archive_dir = vault_root / data["data"]["archive_dir"]+ assert archive_dir.is_dir()+ assert (archive_dir / "loci.json").exists()+ # Dir name is just `archive-<timestamp>`, no slug.+ assert archive_dir.name.startswith("archive-")+++def test_archive_run_handles_repeat_invocations_in_same_second(vault_root: Path):+ """Two archive-runs back to back must not collide on the timestamp suffix."""+ _seed_prior_run(vault_root, vault_tag="run-one")+ r1 = runner.invoke(app, ["archive-run", "--json"])+ assert r1.exit_code == 0, r1.output++ # Re-seed and archive again immediately.+ _seed_prior_run(vault_root, vault_tag="run-one")+ r2 = runner.invoke(app, ["archive-run", "--json"])+ assert r2.exit_code == 0, r2.output++ d1 = json.loads(r1.output)["data"]["archive_dir"]+ d2 = json.loads(r2.output)["data"]["archive_dir"]+ assert d1 != d2+ assert (vault_root / d1).is_dir()+ assert (vault_root / d2).is_dir()+++def test_archive_run_prefers_most_recent_query_file(vault_root: Path):+ """If multiple query-*.md exist, the most recently modified one wins+ as the inferred previous_vault_tag.+ """+ import os+ import time++ research = vault_root / "research"+ _write(research / "scaffold.md", "# Scaffold\n")+ old_query = research / "query-old-tag.md"+ new_query = research / "query-new-tag.md"+ _write(old_query, "old")+ time.sleep(0.05)+ _write(new_query, "new")+ # Make the mtime ordering unambiguous (Windows mtime resolution can blur).+ now = time.time()+ os.utime(old_query, (now - 60, now - 60))+ os.utime(new_query, (now, now))++ result = runner.invoke(app, ["archive-run", "--json"])+ assert result.exit_code == 0, result.output+ data = json.loads(result.output)+ assert data["data"]["previous_vault_tag"] == "new-tag"diff --git a/tests/test_cli/test_vault_tag.py b/tests/test_cli/test_vault_tag.pynew file mode 100644index 0000000..685d915--- /dev/null+++ b/tests/test_cli/test_vault_tag.py@@ -0,0 +1,119 @@+"""Tests for `hyperresearch vault-tag`."""++from __future__ import annotations++import json+import re+from pathlib import Path++import pytest+from typer.testing import CliRunner++from hyperresearch.cli import app++runner = CliRunner()++_TAG_RE = re.compile(r"^[a-z0-9][a-z0-9-]+-[0-9a-f]{6}$")+++def vault_root(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ """Init a vault, chdir into it, return its root."""+ result = runner.invoke(app, ["init", str(tmp_path / "v"), "--name", "Tag Test"])+ assert result.exit_code == 0, result.output+ root = tmp_path / "v"+ monkeypatch.chdir(root)+ return root+++def _invoke(slug: str) -> dict:+ result = runner.invoke(app, ["vault-tag", slug, "--json"])+ assert result.exit_code == 0, result.output+ return json.loads(result.output)+++def test_vault_tag_basic_format(vault_root: Path):+ data = _invoke("efield-dft-sac")["data"]+ assert data["slug"] == "efield-dft-sac"+ assert len(data["suffix"]) == 6+ assert re.fullmatch(r"[0-9a-f]{6}", data["suffix"])+ assert _TAG_RE.match(data["vault_tag"])+ assert data["vault_tag"].startswith("efield-dft-sac-")+++def test_vault_tag_repeated_calls_produce_distinct_tags(vault_root: Path):+ """Same slug, two invocations — must yield different suffixes. This is+ the core collision-avoidance property: a user re-running the SAME+ query produces a fresh tag, so their old final report is never+ overwritten.+ """+ tags = set()+ for _ in range(20):+ data = _invoke("topic")["data"]+ tags.add(data["vault_tag"])+ # secrets.token_hex collisions in 20 draws from 16M-name space are+ # astronomically unlikely; if this ever flakes the suffix generator+ # is broken.+ assert len(tags) == 20+++def test_vault_tag_avoids_existing_query_file(vault_root: Path):+ """If a prior run already produced research/query-topic-aaaaaa.md, the+ new tag must not collide with it.+ """+ research = vault_root / "research"+ (research / "query-topic-aaaaaa.md").write_text("prior")+ # Bias the test by hammering the same slug 30x; each must dodge the+ # reserved suffix.+ for _ in range(30):+ data = _invoke("topic")["data"]+ assert data["vault_tag"] != "topic-aaaaaa"+++def test_vault_tag_avoids_existing_final_report(vault_root: Path):+ """Final reports also lock a suffix even if the corresponding query+ file got moved or deleted.+ """+ notes = vault_root / "research" / "notes"+ notes.mkdir(parents=True, exist_ok=True)+ (notes / "final_report_topic-cafe42.md").write_text("---\ntitle: x\n---\n")+ for _ in range(30):+ data = _invoke("topic")["data"]+ assert data["vault_tag"] != "topic-cafe42"+++def test_vault_tag_ignores_legacy_without_suffix_tag(vault_root: Path):+ """A pre-namespacing vault may have query-topic.md with no hex suffix.+ That format can't collide with the new suffix-style tags (different+ length), so we just need to confirm the command runs cleanly and+ produces a valid suffixed tag.+ """+ research = vault_root / "research"+ (research / "query-topic.md").write_text("legacy")+ data = _invoke("topic")["data"]+ assert _TAG_RE.match(data["vault_tag"])+ assert data["vault_tag"] != "topic"+++def test_vault_tag_rejects_invalid_slugs(vault_root: Path):+ # `--` separates options from positional args so typer doesn't try to+ # interpret leading-dash slugs as flags.+ bad = ["Topic", "topic with spaces", "topic_underscore", "-leading-dash", ""]+ for slug in bad:+ result = runner.invoke(app, ["vault-tag", "--json", "--", slug])+ assert result.exit_code == 1, f"slug {slug!r} should have been rejected"+ data = json.loads(result.output)+ assert data["ok"] is False+ assert data["error_code"] == "INVALID_SLUG"+++def test_vault_tag_works_without_vault_only_fails_cleanly(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):+ """If the user runs vault-tag outside a vault, the command exits+ nonzero with a NO_VAULT error code rather than crashing.+ """+ monkeypatch.chdir(tmp_path)+ result = runner.invoke(app, ["vault-tag", "topic", "--json"])+ assert result.exit_code == 1+ data = json.loads(result.output)+ assert data["ok"] is False+ assert data["error_code"] == "NO_VAULT"diff --git a/tests/test_core/test_sync.py b/tests/test_core/test_sync.pyindex 9d7010a..09a4d45 100644--- a/tests/test_core/test_sync.py+++ b/tests/test_core/test_sync.py@@ -123,3 +123,138 @@ def test_sync_excludes_research_root_staging_files(tmp_vault):assert "scaffold.md" not in added_namesassert "comparisons.md" not in added_namesassert "synthesis.md" not in added_names+++def test_sync_skips_frontmatterless_scratch_files(tmp_vault):+ """Issue #25: agent subagents write plain-markdown scratch body files+ under research/temp/ (e.g. interim-report-<locus>.md) before passing+ them to `note new --body-file`. Those files MUST NOT enter the note+ index — they collide on derived id with the canonical notes created+ from them and silently smash the canonical row's path.+ """+ from hyperresearch.core.note import write_note++ # Canonical note (frontmatter present).+ write_note(tmp_vault.notes_dir, "Interim Report Foo", body="# Real\n", note_id="interim-report-foo")++ # Scratch body file at research/temp/ (no frontmatter).+ tmp_vault.temp_dir.mkdir(parents=True, exist_ok=True)+ (tmp_vault.temp_dir / "interim-report-foo.md").write_text("# Interim report: foo\n\nbody\n")++ # Also: nested temp/ inside an arbitrary sub-tree (e.g. run-dir layout).+ nested = tmp_vault.research_dir / "runs" / "abc" / "temp"+ nested.mkdir(parents=True)+ (nested / "scratch.md").write_text("body without frontmatter\n")++ plan = compute_sync_plan(tmp_vault)++ added_rels = [str(p.relative_to(tmp_vault.root)).replace("\\", "/") for p in plan.to_add]+ assert "research/notes/interim-report-foo.md" in added_rels+ assert all("temp/" not in r for r in added_rels)++ result = execute_sync(tmp_vault, plan)+ assert result.added == 1+ assert result.errors == []++ # The canonical note's path is what's in the DB, not the scratch path.+ row = tmp_vault.db.execute(+ "SELECT path FROM notes WHERE id = ?", ("interim-report-foo",)+ ).fetchone()+ assert row["path"] == "research/notes/interim-report-foo.md"+++def test_sync_includes_stub_notes_in_temp(tmp_vault):+ """research/temp/ doubles as the home for stub notes the `graph stub`+ command creates to resolve broken wiki-links. Those notes carry full+ YAML frontmatter and MUST continue to sync — the issue #25 fix is+ content-based, not path-based, precisely to keep this working.+ """+ from hyperresearch.core.note import write_note++ write_note(+ tmp_vault.temp_dir,+ "Stub Topic",+ body="# Stub Topic\n\n*Stub — created to resolve a broken link.*\n",+ note_id="stub-topic",+ status="draft",+ summary="Stub for [[stub-topic]]",+ )++ plan = compute_sync_plan(tmp_vault)+ added_names = [p.name for p in plan.to_add]+ assert "stub-topic.md" in added_names++ result = execute_sync(tmp_vault, plan)+ assert result.added == 1+ assert result.errors == []+ row = tmp_vault.db.execute("SELECT id FROM notes WHERE id = ?", ("stub-topic",)).fetchone()+ assert row is not None+++def test_sync_surfaces_duplicate_id_collision_as_error(tmp_vault):+ """Defense-in-depth (#25): if a new file claims an id already owned by+ another file in the vault, the second one must NOT silently smash the+ first's row. Surface it as a result.errors entry instead.+ """+ from hyperresearch.core.note import write_note++ # Establish the canonical first.+ write_note(tmp_vault.notes_dir, "Topic", note_id="topic", body="# Topic A\n")+ plan1 = compute_sync_plan(tmp_vault)+ result1 = execute_sync(tmp_vault, plan1)+ assert result1.added == 1+ assert result1.errors == []++ # Drop a second file elsewhere that hand-rolls the same id in frontmatter.+ tmp_vault.temp_dir.mkdir(parents=True, exist_ok=True)+ (tmp_vault.temp_dir / "duplicate.md").write_text(+ "---\nid: topic\ntitle: Topic Duplicate\n---\n\n# Topic B\n"+ )++ plan2 = compute_sync_plan(tmp_vault)+ result2 = execute_sync(tmp_vault, plan2)++ assert result2.added == 0+ assert len(result2.errors) == 1+ assert "id collision" in result2.errors[0]["error"]++ # The canonical path is preserved.+ row = tmp_vault.db.execute("SELECT path FROM notes WHERE id = ?", ("topic",)).fetchone()+ assert row["path"] == "research/notes/topic.md"+++def test_sync_cleans_up_stale_collided_row(tmp_vault):+ """Pre-fix vaults can have a DB row whose `path` points into research/temp/+ (the scratch file won the UPSERT race). After the fix lands, that file no+ longer enters the sync plan as an add/update; instead it appears in+ `to_delete` so the bad row goes away on the next sync. The canonical+ file then re-adds cleanly.+ """+ from hyperresearch.core.note import write_note++ # Simulate the pre-fix DB state directly.+ write_note(tmp_vault.notes_dir, "Foo", note_id="foo", body="# Foo\n")+ plan = compute_sync_plan(tmp_vault)+ execute_sync(tmp_vault, plan)++ # Stamp the DB row's path onto a scratch location, as the old race would.+ tmp_vault.db.execute(+ "UPDATE notes SET path = ? WHERE id = ?",+ ("research/temp/foo.md", "foo"),+ )+ tmp_vault.db.commit()+ tmp_vault.temp_dir.mkdir(parents=True, exist_ok=True)+ (tmp_vault.temp_dir / "foo.md").write_text("scratch body without frontmatter\n")++ plan2 = compute_sync_plan(tmp_vault)+ # The scratch file is not in to_add (no frontmatter); the stale db path+ # is in to_delete; the canonical file is in to_add.+ to_delete_paths = list(plan2.to_delete)+ to_add_rels = [str(p.relative_to(tmp_vault.root)).replace("\\", "/") for p in plan2.to_add]+ assert "research/temp/foo.md" in to_delete_paths+ assert "research/notes/foo.md" in to_add_rels++ result = execute_sync(tmp_vault, plan2)+ assert result.errors == []+ row = tmp_vault.db.execute("SELECT path FROM notes WHERE id = ?", ("foo",)).fetchone()+ assert row["path"] == "research/notes/foo.md"