headquarter/openspec/specs/instance-runtime-health/spec.md at fix/workspace-mount-bind-mount

Files

T

Fusion 063a839790 feat: implement repository clone mode with SSH key support

- Add clone_mode and branch fields to tool_instances
- Add ssh_key_id to git_repositories for per-repo SSH key assignment
- Implement host-side git cloning with branch selection (default: main)
- Mount SSH keys into containers for git operations in clone mode
- Add dirty state check on clone-mode instance deletion with confirmation
- Update SessionsPage with mount/clone selector, branch input, SSH key display
- Add SSH key selector to repository creation form
- Add dirty delete confirmation modal with changed files list
- Update API schemas and endpoints for new fields
- Sync delta specs to main specs (git-repo, tool-instances, repo-clone-mode)
- Archive completed OpenSpec change: repo-clone-mode-with-ssh
- Document git requirement for custom tool types

Quality gates: Frontend typecheck and build passed
OpenSpec: repo-clone-mode-with-ssh archived with all tasks complete

2026-05-22 22:56:35 +02:00

2.3 KiB

Raw Permalink Blame History

ADDED Requirements

Requirement: Runtime health endpoint

The system SHALL provide a health endpoint that checks both container and tunnel health.

Scenario: Full health check

GIVEN a running web-enabled instance
WHEN GET /instances/{id}/health is called
THEN the response includes:
- container_status: "running", "exited", "restarting", or "not_found"
- container_health: "healthy", "unhealthy", or null (if no Docker healthcheck)
- tunnel_status: "healthy", "unreachable", or "error_response"
- tunnel_status_code: the HTTP status code from the tunnel URL, or null
- probe_status: "passed", "failed", "pending", or "not_configured"
- healthy: true only if container is running AND tunnel is healthy

Scenario: Health check for terminal-only instance

GIVEN a running terminal-only instance
WHEN GET /instances/{id}/health is called
THEN the response includes container_status: "running"
AND tunnel_status: "not_applicable"
AND healthy: true if container is running

Requirement: Continuous health polling

The system SHALL support periodic health checks from the frontend.

Scenario: Frontend health polling

GIVEN active instances in the UI
WHEN the frontend polls health every 30 seconds
THEN the health status is displayed as a badge
AND the badge shows "tunnel error" only when tunnel is unreachable
AND the badge shows "app error" when tunnel returns 502/503/504
AND the badge shows "starting" when container is up but probe is pending

Requirement: Container state synchronization

The system SHALL update instance status when container state changes unexpectedly.

Scenario: Container crashes

GIVEN an instance with status "running"
WHEN the container exits (crash or OOM)
AND a health check is performed
THEN the instance status is updated to "error"
AND the container exit code and logs are captured

Scenario: Container stopped externally

GIVEN an instance with status "running"
WHEN the container is stopped via docker command outside the system
AND a health check is performed
THEN the instance status is updated to "stopped"

MODIFIED Requirements

None.

REMOVED Requirements