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

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.md
index 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 system
diff --git a/pyproject.toml b/pyproject.toml
index 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__.py
index 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_run
from hyperresearch.cli.dedup import dedup as _dedup
from hyperresearch.cli.fetch import fetch as _fetch
from hyperresearch.cli.import_cmd import import_vault as _import
@@ -71,6 +72,7 @@ from hyperresearch.cli.research import research as _research
from hyperresearch.cli.search import search as _search
from hyperresearch.cli.serve import serve as _serve
from hyperresearch.cli.tag import tag_list as _tags
+from hyperresearch.cli.vault_tag import vault_tag as _vault_tag
from hyperresearch.cli.watch import watch as _watch
app.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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index cb9be24..ddf7082 100644
--- a/src/hyperresearch/core/sync.py
+++ b/src/hyperresearch/core/sync.py
@@ -3,6 +3,7 @@
from __future__ import annotations
import hashlib
+import re
import sqlite3
import time
from 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):
+ continue
rel = 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 deletes
for rel_path in plan.to_delete:
@@ -124,20 +183,16 @@ def execute_sync(vault, plan: SyncPlan) -> SyncResult:
# Process adds
for 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 += 1
except Exception as e:
result.errors.append({"path": str(file_path), "error": str(e)})
# Process updates
for 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 += 1
except 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.md
index 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`:
```markdown
diff --git a/tests/test_cli/test_archive.py b/tests/test_cli/test_archive.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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_names
assert "comparisons.md" not in added_names
assert "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"