Skip to content

feat: Add run execution management with runtime adapters (ISSUE-005)#7

Open
proboscis wants to merge 2 commits intomainfrom
issue/ISSUE-005/run-20251228-154851
Open

feat: Add run execution management with runtime adapters (ISSUE-005)#7
proboscis wants to merge 2 commits intomainfrom
issue/ISSUE-005/run-20251228-154851

Conversation

@proboscis
Copy link
Owner

Summary

  • Implements run execution management for runbox (ISSUE-005)
  • Adds RuntimeAdapter trait with BackgroundAdapter and TmuxAdapter implementations
  • Extends Run structure with status, runtime, handle, log_ref, timeline, exit_code fields
  • Adds CLI commands: ps, stop, logs, attach
  • Updates run command with --runtime bg|tmux option
  • Enhances show command with detailed run information

Key Features

Runtime Adapters

  • BackgroundAdapter: Spawns processes in background with pid/pgid tracking
  • TmuxAdapter: Spawns processes in tmux windows for interactive access

CLI Commands

Command Description
runbox run -t <template> --runtime bg|tmux Start a run in specified runtime
runbox ps [--status running] List runs with automatic status reconciliation
runbox stop <run_id> Stop a running process
runbox logs <run_id> [-f] View run logs (with optional follow mode)
runbox attach <run_id> Attach to tmux window
runbox show <run_id> Show detailed run information

Architecture

┌─────────────────────────────────────────────────────┐
│ runbox core                                         │
│  - 台帳管理(Run CRUD)                              │
│  - ログファイル管理                                   │
│  - 状態遷移(status 更新)                           │
│  - reconcile(状態整合性チェック)                    │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────┐
│ RuntimeAdapter trait                                │
│  - spawn(): プロセス起動 → RuntimeHandle            │
│  - stop(): 停止                                     │
│  - attach(): 端末接続                               │
│  - is_alive(): 生存確認                             │
└─────────────────────────────────────────────────────┘
         │                │
         ▼                ▼
┌─────────────┐  ┌─────────────┐
│ Background  │  │    Tmux     │
│   Adapter   │  │   Adapter   │
└─────────────┘  └─────────────┘

Test plan

  • All existing tests pass (23 tests)
  • New runtime adapter tests pass
  • Manual testing of runbox run --runtime bg with a template
  • Manual testing of runbox ps to list runs
  • Manual testing of runbox stop to stop a run
  • Manual testing of runbox logs -f to follow logs
  • Manual testing of runbox run --runtime tmux (requires tmux)
  • Manual testing of runbox attach (requires tmux)

Related Issues

  • Implements: ISSUE-005 (Run Execution Management)
  • Depends on: ISSUE-001 (Run/RunTemplate/Playlist Spec)
  • Related: ISSUE-006 (Short ID Support) - partially implemented

🤖 Generated with Claude Code

proboscis and others added 2 commits December 28, 2025 15:56
This PR implements execution management for runbox, adding the ability
to spawn, monitor, and control running processes in different runtimes.

## Changes

### Run Structure Extension
- Added `status`, `runtime`, `handle`, `log_ref`, `timeline`, `exit_code` fields
- Added `RunStatus` enum (Pending, Running, Exited, Failed, Killed, Unknown)
- Added `RuntimeHandle` enum for runtime-specific data
- Added `LogRef` and `Timeline` structs
- Backwards compatible with existing Run JSON files

### RuntimeAdapter Trait
- Defined trait for runtime adapters with spawn/stop/attach/is_alive methods
- Implemented `BackgroundAdapter` for background processes (pid/pgid management)
- Implemented `TmuxAdapter` for tmux session/window management

### CLI Commands
- `runbox run --runtime bg|tmux`: Start runs in specified runtime
- `runbox ps [--status <status>]`: List runs with status reconciliation
- `runbox stop <run_id>`: Stop a running process
- `runbox logs <run_id> [-f] [-n <lines>]`: View run logs
- `runbox attach <run_id>`: Attach to tmux window (tmux only)
- `runbox show <run_id>`: Enhanced output with all new fields

### Other
- Added logs directory to storage
- Added `short_id()` method to Run for abbreviated IDs
- Added `reconcile_runs()` for status consistency checking
- Added `find_run()` helper for short ID lookup

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Changes per updated spec:
- Add reconcile_reason field to Run struct
- RuntimeAdapter.stop() now has force parameter (SIGTERM vs SIGKILL)
- TmuxAdapter spawn uses -c for cwd, env prefix, bash -lc
- CAS-style updates: only update status when Running
- Don't overwrite ended_at if already set
- Record reconcile_reason when marking as Unknown
- CLI stop command now has --force flag

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant