---
id: OPS-WP-0001
type: workplan
title: "ops-bridge diagnostics and flow improvements"
domain: custodian
repo: ops-bridge
status: done
owner: claude
topic_slug: custodian
created: "2026-03-20"
updated: "2026-03-20"
state_hub_workstream_id: "6726cea2-447a-40b2-b0a0-edf495f07942"
---

# OPS-WP-0001 — ops-bridge diagnostics and flow improvements

**Scope:** Add `bridge check` end-to-end diagnostics command, fix `bridge status` to
surface live PID liveness and flag stale state, add a `bridge_check` MCP tool, and
wire Makefile convenience targets in state-hub.

**Context:** During a session, `bridge status` reported "connected" but the reverse
port forwarding was not active — stale `.state` files written by the daemon. The
status command does not verify the SSH process is alive or that the remote port is
actually listening.

---

## Task: Add `read_raw_pid()` to StateManager

```task
id: OPS-WP-0001-T01
status: done
priority: high
state_hub_task_id: "05e98e85-699a-4982-bb3e-8f2538cde2c7"
```

Add `read_raw_pid(name)` to `src/bridge/state.py` — reads PID from file without
liveness check. Existing `read_pid()` (which also checks liveness) stays unchanged.

---

## Task: Create `src/bridge/diagnostics.py`

```task
id: OPS-WP-0001-T02
status: done
priority: high
state_hub_task_id: "b68d7b1e-850b-469a-9de2-8b5d3d1f1c05"
```

New module with `TunnelCheckResult` dataclass (ssh_process, pid, remote_port,
local_api, latency_ms, stale_state, ok property) and `check_tunnel()` /
`check_all_tunnels()` functions. SSH probe via subprocess; optional httpx health check.

---

## Task: Fix `bridge status` and add `bridge check` to CLI

```task
id: OPS-WP-0001-T03
status: done
priority: high
state_hub_task_id: "e87c6c5d-170c-4af3-905c-a48fae2edbe5"
```

Fix `status` to show live PID liveness (LIVE column) and flag stale state.
Add `check` command with `--json` flag; exit 1 if any tunnel not ok.
Add `_print_check_table` helper.

---

## Task: Add `bridge_check` MCP tool and `bridge://check` resource

```task
id: OPS-WP-0001-T04
status: done
priority: high
state_hub_task_id: "7e97c112-20e2-4e2e-b853-53b10998392b"
```

Add `bridge_check(tunnel?)` tool and `bridge://check` resource to
`src/bridge/mcp_server/server.py`.

---

## Task: Register `bridge_check` capability

```task
id: OPS-WP-0001-T05
status: done
priority: high
state_hub_task_id: "c69fc748-a706-46db-a4d5-30d60222452b"
```

Add `bridge_check` entry to `src/bridge/capabilities.py` with
`required_access_modes=frozenset({"cli", "mcp"})`.

---

## Task: Write `tests/test_diagnostics.py`

```task
id: OPS-WP-0001-T06
status: done
priority: high
state_hub_task_id: "070ed088-74a6-48d3-81cf-739c2a2fd21b"
```

Unit tests: test_no_pid, test_pid_dead, test_pid_alive_port_listening,
test_pid_alive_port_closed, test_ssh_timeout.

---

## Task: Add `TestCheckCommand` to `tests/test_cli.py`

```task
id: OPS-WP-0001-T07
status: done
priority: high
state_hub_task_id: "aae5ddc5-f823-4647-a536-8604ddb97946"
```

Tests: test_check_help, test_check_all_pass (marked capability+mode),
test_check_any_fail, test_check_json_flag, test_check_specific_tunnel.

---

## Task: Add `TestMcpBridgeCheck` to `tests/test_mcp.py`

```task
id: OPS-WP-0001-T08
status: done
priority: high
state_hub_task_id: "ed492a3d-7a5f-465e-8cc3-d2f992f5462c"
```

Test: test_bridge_check_tool marked capability("bridge_check") + access_mode("mcp").

---

## Task: Add tunnels targets to state-hub Makefile

```task
id: OPS-WP-0001-T09
status: done
priority: medium
state_hub_task_id: "a3c77062-cff5-40e3-936c-b210b05f8839"
```

Add `tunnels-up`, `tunnels-status`, `tunnels-check` targets delegating to `bridge`.
Add to `.PHONY` line.

---

## Task: Run test suite and verify

```task
id: OPS-WP-0001-T10
status: done
priority: high
state_hub_task_id: "e42de76c-fab7-4924-8929-38fa9eaca478"
```

`cd /home/worsch/ops-bridge && uv run pytest tests/ -v` — all tests green.