bathos 0.3.0__tar.gz → 0.3.1__tar.gz

{bathos-0.3.0 → bathos-0.3.1}/CHANGELOG.md

@@ -5,6 +5,16 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- **`bth sync` indefinite hang** — `sync_catalog()` now passes SSH options (`ConnectTimeout=10`, `BatchMode=yes`) to rsync so unreachable hosts fail in ≤10 s instead of blocking forever; adds `subprocess.run(timeout=120)` as a safety net; raises `RuntimeError` with actionable message on timeout; drops silent `--progress` flag (output was captured, not displayed)
+
+- **Parquet timestamp timezone-aware fix** — Ensure timestamps loaded from Parquet are timezone-aware (UTC) to avoid comparisons between naive and aware datetimes in query functions; prevents TypeError and incorrect filtering.
+
+---
+
 ## [0.3.0] - 2026-05-20
 
 ### Added

{bathos-0.3.0 → bathos-0.3.1}/CLAUDE.md

@@ -10,15 +10,19 @@ bathos is a standalone experiment tracking CLI for a single researcher across 10
 
 ---
 
-## Current Status (as of 2026-05-15)
+## Current Status (as of 2026-05-20)
 
-**v0.1: complete and merged to main.** 44 tests passing.
+**v0.3.0: complete and merged to main.** 254 tests passing.
 
 - Full design spec: `.praxia/specs/bathos-design.md`
 - v0.1 implementation plan: `.praxia/specs/bathos-v01-plan.md`
-- Backlog: items #124–139 in praxia DB (see below); #124–127 done
+- Backlog: items #124–142 in praxia DB (see below); #124–141 done
 
-**Next sprint candidates (P2):** #128 (FastMCP), #130 (bth check) + #128 unblocked once 130 done, #138 (bth sync), #139 (bth compact / warm tier), #131 (SLURM integration), #132 (bth new-experiment).
+**Shipped in v0.2:** FastMCP server (#128), `@bth.experiment` decorator (#129), `bth check` (#130), SLURM `_bth_env.sh` (#131), `bth new-experiment` (#132), `uv tool` packaging (#133), `bth lint` (#134), `bth migrate` (#135), `bth sync` (#138), schema versioning v2 (#140), `bth archive` (#141), `bth remote` subcommands, `bth export`, `bth catalog-version`.
+
+**Shipped in v0.3:** Agentic integrity gate (`--agent-mode`, `--no-sidecar`, `--derived-from`), lineage tracking (`bth lineage`), campaigns (`bth campaign` subcommands + MCP tools), sprint audit (`bth sprint-audit`), Tier-2 lint checks, schema v3 with campaign/lineage/integrity fields, `--campaign` flag on `bth run`.
+
+**Remaining backlog:** #136 (bth-migrate praxia workflow), #137 (global instruction portability), #142 (results management design).
 
 ---
 
@@ -52,7 +56,7 @@ Cool schema is intentionally minimal (13 provenance fields). Warm adds `metadata
 
 ### Pre-Registration Schemas (per script directory)
 
-Every script in `scripts/experiments/` and `scripts/benchmarks/` must have a companion sidecar **`<script-stem>.bth.toml`** declaring its hypothesis, expected outcomes, and result schema before `bth run` will execute it.
+Every script in `scripts/experiments/` and `scripts/benchmarks/` should have a companion sidecar **`<script-stem>.bth.toml`** declaring its hypothesis, expected outcomes, and result schema. In v0.2+, `bth run` enforces this by default; pass `--no-sidecar` to bypass.
 
 **Sidecar format (experiments):**
 ```toml
@@ -118,7 +122,7 @@ fix = "str"
 | Catalog storage | **DuckDB + Parquet** (not pyiceberg) | pyiceberg is for distributed data lakes; DuckDB+Parquet is simpler, no overhead |
 | FastMCP | Mirror CLI tool-for-tool | `cli.py` and `mcp.py` both thin layers over same core modules |
 
-### Source Layout (planned)
+### Source Layout
 
 ```
 src/bathos/
@@ -133,8 +137,20 @@ src/bathos/
   init.py         # bth init logic
   runner.py       # bth run subprocess wrapper
   query.py        # list_runs, get_run, find_runs, run_sql
-  checker.py      # bth check — git-drift validity (v0.2)
-  sidecar.py      # .bth.toml sidecar parse, content-hash, outcome eval (v0.2)
+  checker.py      # bth check — git-drift freshness gate
+  sidecar.py      # .bth.toml sidecar parse, content-hash, outcome eval
+  campaigns.py    # bth campaign subcommands + Campaign dataclass
+  sprint_audit.py # bth sprint-audit cross-project audit
+  linter.py       # bth lint — Tier-1 and Tier-2 checks
+  migrate.py      # bth migrate — schema version upgrades
+  new_experiment.py # bth new-experiment scaffold
+  export.py       # bth export — skill + MCP registration
+  validate.py     # sidecar structural validation
+  remote.py       # bth remote subcommands
+  sync.py         # bth sync rsync wrapper
+  archive.py      # bth archive warm→cold export
+  prereg.py       # agentic integrity pre-registration gate
+  decorators.py   # @bth.experiment provenance decorator
   templates/
     _bth_env.sh   # SLURM env helper template
     experiment.py # bth new-experiment script skeleton
@@ -150,25 +166,24 @@ src/bathos/
 | 125 | `bth init` — dirs, .bth.toml, catalog bootstrap, SLURM config | P1 | 124 |
 | 126 | `bth run` — CLI wrapper, provenance capture | P1 | 124 |
 | 127 | `bth ls` / `show` / `find` / `sql` — query interface | P1 | 126 |
-| 128 | FastMCP server — mirrors CLI tool-for-tool | P1 | 126, 127, 130 |
-| 129 | `@bth.experiment` — provenance decorator for Typer scripts | P2 | 124 |
-| 130 | `bth check` — freshness/validity vs git HEAD | P2 | 126 |
-| 131 | SLURM `_bth_env.sh` integration | P2 | 125, 126 |
-| 132 | `bth new-experiment` — Typer + sidecar scaffold | P2 | 125 |
-| 133 | `uv tool` packaging + release | P3 | 126–130 |
-| 134 | Script convention linter | P3 | — |
-| 135 | `bth migrate` — Phase 1 mechanical (existing projects) | P2 | 125 |
-| 136 | `bth-migrate` praxia workflow — agentic classification + git mv plan | P2 | 135 |
-| 137 | Global instruction portability (separate design session needed) | P2 | — |
-| 138 | `bth sync` — rsync cool-tier catalog to/from cluster remote | P2 | 125, v0.1 done |
-| 139 | `bth compact` + warm-tier DuckDB (`bth sql` catalog queries) | P2 | v0.1 done |
-| 140 | Schema versioning + extended provenance (hostname, slurm_job_id, metadata JSON, migrations) | P2 | 139 |
-| 141 | `bth archive` — warm→cold partitioned Parquet export | P3 | 139, 140 |
-| 142 | Results management — output convention, file-count utilities, direct management interface design | P2 | 139 |
+| 128 | FastMCP server — mirrors CLI tool-for-tool | P1 ✓ done (v0.2) | 126, 127, 130 |
+| 129 | `@bth.experiment` — provenance decorator for Typer scripts | P2 ✓ done (v0.2) | 124 |
+| 130 | `bth check` — freshness/validity vs git HEAD | P2 ✓ done (v0.1/v0.2) | 126 |
+| 131 | SLURM `_bth_env.sh` integration | P2 ✓ done (v0.1) | 125, 126 |
+| 132 | `bth new-experiment` — Typer + sidecar scaffold | P2 ✓ done (v0.2) | 125 |
+| 133 | `uv tool` packaging + release | P3 ✓ done (v0.2) | 126–130 |
+| 134 | Script convention linter | P3 ✓ done (v0.2) | — |
+| 135 | `bth migrate` — Phase 1 mechanical (existing projects) | P2 ✓ done (v0.2) | 125 |
+| 136 | `bth-migrate` praxia workflow — agentic classification + git mv plan | P2 (not started) | 135 |
+| 137 | Global instruction portability (separate design session needed) | P2 (not started) | — |
+| 138 | `bth sync` — rsync cool-tier catalog to/from cluster remote | P2 ✓ done (v0.2) | 125, v0.1 done |
+| 139 | `bth compact` + warm-tier DuckDB (`bth sql` catalog queries) | P2 ✓ done (v0.1) | v0.1 done |
+| 140 | Schema versioning + extended provenance (hostname, slurm_job_id, metadata JSON, migrations) | P2 ✓ done (v0.2) | 139 |
+| 141 | `bth archive` — warm→cold partitioned Parquet export | P3 ✓ done (v0.2) | 139, 140 |
+| 142 | Results management — output convention, file-count utilities, direct management interface design | P2 (not started) | 139 |
 
 **Not yet backlogged:**
-- Sidecar pre-registration enforcement in `bth run` (add as P2, depends on 126)
-- Outcome evaluation + `runs.outcome` column in warm DuckDB (add as P2, depends on 139)
+- *(none — sidecar enforcement and outcome evaluation shipped in v0.2/v0.3)*
 
 ---
 

{bathos-0.3.0 → bathos-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bathos
-Version: 0.3.0
+Version: 0.3.1
 Summary: Local-first, zero-server experiment tracking for researchers
 Project-URL: Homepage, https://github.com/mariellerossi/bathos
 Project-URL: Documentation, https://bathos.readthedocs.io
@@ -66,13 +66,52 @@ bth run scripts/experiments/benchmark_tip3p.py -- --n-steps 1000 --out outputs/r
 bth ls --since 7d
 bth show <run-id>
 
-# Check if a result is still valid (compares recorded git hash to HEAD)
-bth check outputs/run1.parquet
+# Check catalog runs for git-drift freshness
+bth check [--status <status>] [--check-outputs]
 
 # Escape hatch: raw DuckDB SQL against the catalog
 bth sql "SELECT project_slug, count(*) FROM runs GROUP BY 1"
 ```
 
+### `bth run` flags
+
+**v0.3+ flags:**
+- `--agent-mode collaborative|autonomous` — declare whether this run is agent-driven
+- `--derived-from <run-id>` — record parent run for lineage tracking
+- `--campaign <campaign-id>` — associate this run with a campaign
+- `--no-sidecar` — bypass sidecar enforcement (use for ad-hoc runs)
+
+## CLI Reference
+
+**Core commands:**
+- `bth init` — initialize bathos in a project
+- `bth run` — execute and track an experiment
+- `bth ls` — list recent runs
+- `bth show <run-id>` — display run details
+- `bth find` — search runs by criteria
+- `bth sql` — raw DuckDB query against catalog
+- `bth check` — check catalog runs for git-drift freshness
+- `bth lineage <run-id>` — show ancestor chain following parent_run_id links
+- `bth sprint-audit [--hours N]` — audit recent runs across all registered projects
+- `bth lint [--project-root PATH]` — check scripts/ for naming conventions and missing sidecars
+- `bth new-experiment <name>` — scaffold a new experiment script and sidecar
+- `bth migrate` — upgrade cool-tier Parquet fragments to current schema version
+- `bth export` — export the using-bathos skill and register MCP server
+
+**`bth remote`** — Manage sync remotes
+- `bth remote add <name> <url>` — add an SSH remote for catalog sync
+- `bth remote list` — list configured remotes
+- `bth remote remove <name>` — remove a remote
+- `bth remote test <name>` — test SSH connectivity to a remote
+
+**`bth campaign`** — Manage experiment campaigns (v0.3+)
+- `bth campaign create <id> --hypothesis <text>` — create a new campaign
+- `bth campaign add <run-id> --campaign <id>` — associate a run with a campaign
+- `bth campaign ls` — list campaigns
+- `bth campaign show <id>` — show campaign details and runs
+- `bth campaign review <id>` — statistical summary and anomaly detection
+- `bth campaign conclude <id> --outcome <label>` — close campaign with outcome
+
 ## Script conventions
 
 `bth init` scaffolds the following structure in your project:

{bathos-0.3.0 → bathos-0.3.1}/README.md

@@ -30,13 +30,52 @@ bth run scripts/experiments/benchmark_tip3p.py -- --n-steps 1000 --out outputs/r
 bth ls --since 7d
 bth show <run-id>
 
-# Check if a result is still valid (compares recorded git hash to HEAD)
-bth check outputs/run1.parquet
+# Check catalog runs for git-drift freshness
+bth check [--status <status>] [--check-outputs]
 
 # Escape hatch: raw DuckDB SQL against the catalog
 bth sql "SELECT project_slug, count(*) FROM runs GROUP BY 1"
 ```
 
+### `bth run` flags
+
+**v0.3+ flags:**
+- `--agent-mode collaborative|autonomous` — declare whether this run is agent-driven
+- `--derived-from <run-id>` — record parent run for lineage tracking
+- `--campaign <campaign-id>` — associate this run with a campaign
+- `--no-sidecar` — bypass sidecar enforcement (use for ad-hoc runs)
+
+## CLI Reference
+
+**Core commands:**
+- `bth init` — initialize bathos in a project
+- `bth run` — execute and track an experiment
+- `bth ls` — list recent runs
+- `bth show <run-id>` — display run details
+- `bth find` — search runs by criteria
+- `bth sql` — raw DuckDB query against catalog
+- `bth check` — check catalog runs for git-drift freshness
+- `bth lineage <run-id>` — show ancestor chain following parent_run_id links
+- `bth sprint-audit [--hours N]` — audit recent runs across all registered projects
+- `bth lint [--project-root PATH]` — check scripts/ for naming conventions and missing sidecars
+- `bth new-experiment <name>` — scaffold a new experiment script and sidecar
+- `bth migrate` — upgrade cool-tier Parquet fragments to current schema version
+- `bth export` — export the using-bathos skill and register MCP server
+
+**`bth remote`** — Manage sync remotes
+- `bth remote add <name> <url>` — add an SSH remote for catalog sync
+- `bth remote list` — list configured remotes
+- `bth remote remove <name>` — remove a remote
+- `bth remote test <name>` — test SSH connectivity to a remote
+
+**`bth campaign`** — Manage experiment campaigns (v0.3+)
+- `bth campaign create <id> --hypothesis <text>` — create a new campaign
+- `bth campaign add <run-id> --campaign <id>` — associate a run with a campaign
+- `bth campaign ls` — list campaigns
+- `bth campaign show <id>` — show campaign details and runs
+- `bth campaign review <id>` — statistical summary and anomaly detection
+- `bth campaign conclude <id> --outcome <label>` — close campaign with outcome
+
 ## Script conventions
 
 `bth init` scaffolds the following structure in your project:

{bathos-0.3.0 → bathos-0.3.1}/agent_assets/docs/claude-code-integration.md

@@ -38,14 +38,18 @@ The skill is loaded automatically at session start in Claude Code. In a new sess
 
 | MCP Tool | CLI equivalent | Status |
 |----------|---------------|--------|
-| `run_script` | `bth run` | ✅ Available |
+| `run` | `bth run` | ✅ Available |
 | `list_runs` | `bth ls` | ✅ Available |
 | `get_run` | `bth show <id>` | ✅ Available |
 | `find_runs` | `bth find` | ✅ Available |
 | `run_sql` | `bth sql` | ✅ Available |
 | `compact_catalog` | `bth compact` | ✅ Available |
-| `check_runs` | `bth check` | 🔜 Coming in v0.2 |
-| `archive_runs` | `bth archive` | 🔜 Coming in v0.2 |
+| `check` | `bth check` | ✅ Available |
+| `archive` | `bth archive` | ✅ Available |
+| `campaign_create` | `bth campaign create` | ✅ Available |
+| `campaign_list` | `bth campaign ls` | ✅ Available |
+| `campaign_review` | `bth campaign review` | ✅ Available |
+| `campaign_conclude` | `bth campaign conclude` | ✅ Available |
 
 ## Update
 

{bathos-0.3.0 → bathos-0.3.1}/agent_assets/using_bathos/SKILL.md

@@ -13,7 +13,7 @@ description: "Use when working in any bathos-tracked research project — experi
 
 **Scope:** Single researcher, 10+ projects, SLURM cluster integration.
 
-**Status:** ✅ v0.2 shipped — 207 tests passing. Full CLI + MCP server available.
+**Status:** ✅ v0.3.0 shipped — 254 tests passing. Full CLI + MCP server available, including campaigns and agentic integrity gates.
 
 ---
 
@@ -34,7 +34,7 @@ description: "Use when working in any bathos-tracked research project — experi
 | Command | Arguments | Status | Notes |
 |---------|-----------|--------|-------|
 | bth init | --slug, --remote, --slurm-partition | ✅ | Project initialization |
-| bth run | <script> [-- args], --tag, --out, --campaign, --agent-mode, --no-sidecar | ✅ | Execute + provenance capture |
+| bth run | <script> [-- args], --tag, --out, --campaign, --agent-mode, --derived-from, --no-sidecar | ✅ | Execute + provenance capture; v0.3: `--agent-mode` (collaborative/autonomous), `--derived-from` (lineage), `--campaign` (campaign association), `--no-sidecar` (bypass enforcement) |
 | bth ls | --since, --status, --limit, --project | ✅ | List recent runs + OUTCOME column |
 | bth show | <run-id> | ✅ | Full run details + git state |
 | bth find | --project, --since, --status, --tag, --output-file | ✅ | Flexible filtered query |

{bathos-0.3.0 → bathos-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bathos"
-version = "0.3.0"
+version = "0.3.1"
 description = "Local-first, zero-server experiment tracking for researchers"
 readme = "README.md"
 requires-python = ">=3.12"

{bathos-0.3.0 → bathos-0.3.1}/src/bathos/schema.py

@@ -137,6 +137,9 @@ class Run:
         ts = pydict["timestamp"][i]
         if not isinstance(ts, datetime):
             ts = ts.as_py()
+        # Ensure timestamp is timezone-aware in UTC for internal comparisons
+        if ts.tzinfo is None:
+            ts = ts.replace(tzinfo=UTC)
         return cls(
             id=pydict["id"][i],
             project_slug=pydict["project_slug"][i],

{bathos-0.3.0 → bathos-0.3.1}/src/bathos/sync.py

@@ -7,6 +7,8 @@ from pathlib import Path
 
 from bathos.config import ProjectConfig
 
+_SYNC_TIMEOUT_S = 120  # rsync kill switch: fail if no completion within 2 minutes
+
 
 @dataclass
 class SyncResult:
@@ -53,17 +55,30 @@ def sync_catalog(
         src = str(local_runs) + "/"
         dst = remote_runs
 
-    # Construct rsync command
+    # ConnectTimeout=10: fail in 10s if host is unreachable rather than hanging
+    # BatchMode=yes: never prompt for a password — fail immediately instead
+    ssh_opts = "ssh -o ConnectTimeout=10 -o BatchMode=yes"
+
     cmd = [
         "rsync",
-        "-azP",
+        "-az",
+        "--partial",
+        f"-e{ssh_opts}",
         "--ignore-existing",
         src,
         dst,
     ]
 
     start_time = time.time()
-    result = subprocess.run(cmd, capture_output=True, text=True)
+    try:
+        result = subprocess.run(
+            cmd, capture_output=True, text=True, timeout=_SYNC_TIMEOUT_S
+        )
+    except subprocess.TimeoutExpired:
+        raise RuntimeError(
+            f"bth sync timed out after {_SYNC_TIMEOUT_S}s — "
+            "check that the remote host is reachable and SSH keys are configured"
+        )
     duration_s = time.time() - start_time
 
     if result.returncode != 0:

{bathos-0.3.0 → bathos-0.3.1}/tests/test_cluster_workflow.py

@@ -177,7 +177,7 @@ remote_root = "~/projects/testproj"
 
         # Verify rsync command structure
         assert cmd[0] == "rsync"
-        assert "-azP" in cmd
+        assert "-az" in cmd
         assert "--ignore-existing" in cmd
         # Should have source and destination with runs/ directories
         assert any("runs/" in str(arg) for arg in cmd)

{bathos-0.3.0 → bathos-0.3.1}/tests/test_sync.py

@@ -40,14 +40,59 @@ def test_sync_constructs_correct_rsync_command_push(tmp_path: Path):
 
         # Should be rsync command
         assert cmd[0] == "rsync"
-        # Should have -azP flags
-        assert "-azP" in cmd
+        # Should have -az flags (no -P: progress is useless when output is captured)
+        assert "-az" in cmd
+        # Should pass SSH options for fast failure: ConnectTimeout + BatchMode
+        assert any("ConnectTimeout" in str(a) for a in cmd)
+        assert any("BatchMode=yes" in str(a) for a in cmd)
         # Should have --ignore-existing flag
         assert "--ignore-existing" in cmd
         # Should reference runs directories
         assert any("runs/" in str(arg) for arg in cmd)
 
 
+def test_sync_passes_timeout_to_subprocess(tmp_path: Path):
+    """sync_catalog passes a timeout to subprocess.run so it cannot hang forever."""
+    config = ProjectConfig(
+        slug="test",
+        root=Path("/home/user/test"),
+        remotes={"engaging": {"host": "engaging", "remote_root": "~/projects/test"}},
+    )
+    catalog_dir = tmp_path / "catalog"
+    catalog_dir.mkdir()
+    (catalog_dir / "runs").mkdir()
+
+    with patch("bathos.sync.subprocess.run") as mock_run:
+        mock_run.return_value.returncode = 0
+        mock_run.return_value.stdout = ""
+
+        sync_catalog("engaging", config, catalog_dir, pull=False)
+
+        call_kwargs = mock_run.call_args[1]
+        assert "timeout" in call_kwargs, "subprocess.run must have a timeout to prevent indefinite hangs"
+        assert call_kwargs["timeout"] > 0
+
+
+def test_sync_raises_on_timeout(tmp_path: Path):
+    """sync_catalog raises RuntimeError with clear message when rsync times out."""
+    import subprocess as _subprocess
+
+    config = ProjectConfig(
+        slug="test",
+        root=Path("/home/user/test"),
+        remotes={"engaging": {"host": "engaging", "remote_root": "~/projects/test"}},
+    )
+    catalog_dir = tmp_path / "catalog"
+    catalog_dir.mkdir()
+    (catalog_dir / "runs").mkdir()
+
+    with patch("bathos.sync.subprocess.run") as mock_run:
+        mock_run.side_effect = _subprocess.TimeoutExpired(cmd=["rsync"], timeout=120)
+
+        with pytest.raises(RuntimeError, match="timed out"):
+            sync_catalog("engaging", config, catalog_dir, pull=False)
+
+
 def test_sync_pull_reverses_direction(tmp_path: Path):
     """sync_catalog pulls from remote when pull=True."""
     config = ProjectConfig(

{bathos-0.3.0 → bathos-0.3.1}/uv.lock

@@ -57,7 +57,7 @@ wheels = [
 
 [[package]]
 name = "bathos"
-version = "0.3.0"
+version = "0.3.1"
 source = { editable = "." }
 dependencies = [
     { name = "duckdb" },