headquarter/openspec/changes/archive/2026-06-14-completed-specs-archive/tool-instances/spec.md

MODIFIED Requirements

Requirement: Status Monitoring

The system SHALL track tool status with startup and health states.

Scenario: Status check with health details

• GIVEN a tool instance
• WHEN status is queried
• THEN the real-time container status is returned:
  • pending: Instance created, container not yet started
  • starting: Container is running, readiness probe in progress
  • running: Container is running and probe passed (or terminal tool)
  • unhealthy: Container is running but probe failed/timed out
  • stopped: Container was stopped by user
  • error: Container failed to start or crashed

ADDED Requirements

Requirement: Health check endpoint enhancement

The system SHALL provide detailed health information through the health check endpoint.

Scenario: Health check with container and tunnel status

• GIVEN a running instance
• WHEN GET /instances/{id}/health is called
• THEN the response includes:
  • healthy: boolean - overall health
  • container_status: "running", "exited", "restarting", or "not_found"
  • tunnel_status: "healthy", "unreachable", "error_response", or "not_applicable"
  • tunnel_status_code: HTTP status code or null
  • probe_status: "passed", "failed", "pending", or "not_configured"
  • last_probe_output: string or null

Requirement: Smart tunnel recreation

The system SHALL only allow tunnel recreation when the tunnel itself is broken.

Scenario: Recreate tunnel for unreachable tunnel

• GIVEN an instance with tunnel_status: "unreachable"
• WHEN the recreate tunnel endpoint is called
• THEN the tunnel is recreated
• AND the new URL is returned

Scenario: Block recreation for application errors

• GIVEN an instance with tunnel_status: "error_response" (e.g., HTTP 502)
• WHEN the recreate tunnel endpoint is called
• THEN the request is rejected with 400 Bad Request
• AND the error message explains the tunnel is working but the application is returning errors

Requirement: Clone mode instance creation

The system SHALL support creating tool instances with a clone mode that clones the repository into the instance directory.

Scenario: Create instance in clone mode

• GIVEN an authenticated user with a repository that has an SSH key and remote URL
• WHEN they create an instance with clone_mode: "clone" and branch: "main"
• THEN the system clones the repository into the instance directory
• AND the compose file uses the clone path as REPO_PATH
• AND the instance record stores clone_mode="clone" and branch="main"

Scenario: Create instance in mount mode

• GIVEN an authenticated user with a repository
• WHEN they create an instance with clone_mode: "mount" (or omit the field)
• THEN the compose file uses the host repository path as REPO_PATH
• AND the instance record stores clone_mode="mount"

Requirement: SSH key mounting for git operations

The system SHALL mount the repository's SSH key into clone-mode containers for git operations.

Scenario: Start clone-mode instance

• GIVEN a clone-mode instance with an associated SSH key
• WHEN the instance is started
• THEN the SSH key is decrypted and written to instance_dir/.ssh/
• AND the .ssh directory is mounted into the container
• AND the container can perform git push/pull operations

Requirement: Dirty check on clone deletion

The system SHALL check for uncommitted changes before deleting a clone-mode instance.

Scenario: Delete clean clone

• GIVEN a clone-mode instance with no uncommitted changes
• WHEN the user requests deletion
• THEN the instance is deleted successfully

Scenario: Delete dirty clone with confirmation

• GIVEN a clone-mode instance with uncommitted changes
• WHEN the user requests deletion
• THEN the system returns a warning with change details
• AND the user must confirm deletion

Scenario: Force delete dirty clone

• GIVEN a clone-mode instance with uncommitted changes
• WHEN the user requests deletion with force=true
• THEN the instance is deleted regardless of uncommitted changes

REMOVED Requirements

None.