# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# ops-bridge — Claude Code Instructions

**Purpose:** SSH reverse tunnel lifecycle manager. Keeps remote execution
environments (COULOMBCORE, Railiance nodes) connected to the local Custodian
State Hub so Claude Code sessions on those machines have full MCP connectivity.

**Domain:** custodian
**Repo slug:** ops-bridge
**Repo ID:** 1bf99f56-6e94-4379-a9ea-295a4c181889

## Custodian State Hub Integration

State Hub: http://127.0.0.1:8000

### Session Protocol

**Step 1 — Orient**
```
get_domain_summary("custodian")
```

**Step 2 — Scan workplans**
```
ls workplans/
```

**During work:** use `record_decision()`, `add_progress_event()`, `resolve_decision()`.

**Session close:** `add_progress_event()` with workstream_id.

If workplan files were modified, run from `~/the-custodian/state-hub/`:
```bash
make fix-consistency REPO=ops-bridge
```

### Workplan Convention (ADR-001)

File location: `workplans/BRIDGE-WP-NNNN-<slug>.md`
Prefix: `BRIDGE-WP`

## What this repo builds

A CLI tool (`bridge`) that manages named SSH reverse tunnels:

```
bridge up [TUNNEL]      # start tunnel(s)
bridge down [TUNNEL]    # stop tunnel(s)
bridge restart [TUNNEL] # restart tunnel(s)
bridge status           # show all tunnels: state, uptime, last health check
bridge logs [TUNNEL]    # tail reconnect log
```

Config file: `~/.config/bridge/tunnels.yaml`

Each tunnel:
- Named (e.g. `state-hub-coulombcore`)
- Reverse SSH port-forward: `ssh -R remote_port:127.0.0.1:local_port host`
- Auto-reconnects on drop (backoff loop)
- Optional HTTP health check to confirm the forwarded service is reachable

PRD: `workplans/BRIDGE-WP-0001-initial-implementation.md`

## Stack

- **Language:** Python 3.11+
- **CLI framework:** Typer
- **Dependencies:** typer, pyyaml, httpx
- **Packaging:** `uv tool install` (single command install, no venv activation)
- **No system daemons** — process management is internal, PID tracked in
  `~/.local/state/bridge/`

## Dev Commands

```bash
# Install locally for development
uv tool install -e .

# Run tests
uv run pytest

# Run a single test
uv run pytest tests/test_tunnel.py::test_name -v

# Lint
uv run ruff check .
```

## Architecture

OpsBridge has two logical components:

**1. OpsBridge — tunnel lifecycle manager** (this repo)
Manages named SSH reverse tunnels defined in `~/.config/bridge/tunnels.yaml`.
Each tunnel runs in a subprocess with a reconnect backoff loop; PIDs are tracked
in `~/.local/state/bridge/`. Bridge states: `stopped → starting → connected →
degraded → failed`. The `degraded` state means SSH is up but the optional HTTP
health check is failing.

**2. OpsCatalog — operations knowledge repository** (planned extension)
A Git-backed YAML catalog of operations domains, targets, bridges, and actor
classes. OpsBridge consumes this catalog to resolve bridge identifiers and
orient operators. Schema examples are in `wiki/OpsCatalogSpecification.md`.
The catalog layout follows: `opscatalog/domains/<domain>/{domain.yaml,
targets/, bridges/, docs/}`.

Key design constraints:
- OpsBridge owns lifecycle management only; it does not own identity/credentials
- Each tunnel is identified by name (e.g. `state-hub-coulombcore`); names used
  in config, CLI args, and log filenames must stay consistent
- Actor attribution (human operator vs. automation agent) is tracked per bridge
  for audit log traceability (FRS §5.7)

Specification docs are in `wiki/`: PRD (`OpsBridgePrd.md`), FRS
(`OpsBridgeFrs.md`), and OpsCatalog spec (`OpsCatalogSpecification.md`).

## Repo boundary

This repo owns **tunnel lifecycle management only**. It does not own:
- State hub code → `the-custodian/state-hub/`
- SSH key management → `railiance-infra/` (S1) or user dotfiles
- Ansible/provisioning → `railiance-infra/`

## Quick Reference

`~/the-custodian/state-hub/mcp_server/TOOLS.md`