headquarter/openspec/changes/session-management-fixes/specs/tool-instances/spec.md

MODIFIED Requirements

Requirement: Tool Lifecycle

The system SHALL manage tool lifecycle operations including tunnel recreation.

Scenario: Stop tool

• GIVEN a running tool instance
• WHEN the user stops it
• THEN docker compose stop is executed
• AND the cloudflared tunnel process is terminated
• AND status is updated to "stopped"

Scenario: Start tool

• GIVEN a stopped tool instance
• WHEN the user starts it
• THEN docker compose start is executed
• AND a new temporary Cloudflare tunnel is created
• AND status is updated to "running"

Scenario: Recreate tunnel

• GIVEN a running tool instance with a broken tunnel
• WHEN the user requests tunnel recreation
• THEN the existing cloudflared process is terminated
• AND a new temporary Cloudflare tunnel is created
• AND the instance URL is updated
• AND the instance shows as healthy

ADDED Requirements

Requirement: Tunnel Health Check

The system SHALL check tunnel health for running instances.

Scenario: Healthy tunnel check

• GIVEN a running instance with an active tunnel
• WHEN the health check runs
• THEN the tunnel URL responds with HTTP 2xx
• AND the instance is marked as healthy

Scenario: Broken tunnel check

• GIVEN a running instance with a broken tunnel
• WHEN the health check runs
• THEN the tunnel URL does not respond with HTTP 2xx
• AND the instance is marked with tunnel_error
• AND a "Recreate Tunnel" button is shown