Control CLI
Contract
| Field |
Bound contract |
| Trigger |
Reproduce, profile, or verify CLI/TUI behavior. |
| Authority |
Reversible local: writes only temporary transcript or profile artifacts under a system temp directory and may spawn local PTY sessions; rollback is terminating the PTY process and removing its runtime scratch. No remote mutation. No source or VCS mutation. No credential or paid mutation. |
| Side effect |
Runs temporary terminal sessions and captures evidence. |
| Done |
A deterministic transcript or profile proof artifact exists and the live PTY session is terminated with its runtime scratch removed. |
Inputs
- The CLI/TUI binary or command to exercise (must be supplied).
- The exact reproduction steps, profile target, or verification scenario (must be supplied).
- Optional: expected output, timeout, and environment variables.
Procedure
- Create a fresh session directory under the system temp path for the captured artifact and PTY/tmux runtime scratch. Record the directory for cleanup. Done when: the session directory is created and recorded.
- Spawn the target CLI/TUI under a PTY, or a tmux session attached to a PTY, so interactive behavior is observable. Apply one action per observation: send one input, then capture the full terminal render before sending the next. Done when: the PTY or tmux session is spawned and interactive behavior is observable.
- For reproduction: drive the supplied steps in order, appending the terminal state after each action to the transcript artifact. Done when: every step is driven in order and the transcript artifact captures the terminal state after each action.
- For profiling: run the target under the chosen profiler, capturing timing or allocation output into the profile artifact. Done when: the profile artifact captures timing or allocation output.
- For verification: exercise the scenario, compare the observed output against the expected output when supplied, and record the pass or fail classification in the transcript artifact. Done when: the pass or fail classification is recorded in the transcript artifact.
- Terminate the PTY process, or detach and kill the tmux session. Done when: the PTY process or tmux session is terminated.
- Remove the PTY/tmux runtime scratch (pipes and sockets); the captured transcript or profile artifact file remains as the retained proof. Done when: runtime scratch is removed and the artifact file remains.
Failure and recovery
- PTY spawn failure or binary not found: record the error in the transcript, do not invent output, and return blocked with the spawn error.
- Timeout: terminate the PTY process, append the partial transcript up to the timeout, and return blocked with the timeout boundary.
- Non-deterministic output: run a second capture, record the observed variance, mark the proof non-deterministic, and return blocked rather than asserting a false pass.
- Any failure: terminate the PTY or tmux process and remove its runtime scratch before returning; if no artifact was captured, delete the whole temp session directory. Never swallow errors or claim the done predicate holds when the proof is missing or inconclusive.
Output
Transcript or profile artifact containing captured terminal evidence, plus final classification: reproduced, profiled, verified-pass, verified-fail, blocked, or non-deterministic. Live PTY session terminated and runtime scratch removed before return.
1---2name: control-cli3description: Use when asked to reproduce, profile, or verify CLI/TUI behavior. Produces a deterministic transcript or profile proof with session cleanup. Not for CLI design advice, use cli-for-agents.4---56# Control CLI78## Contract910| Field | Bound contract |11|---|---|12| Trigger | Reproduce, profile, or verify CLI/TUI behavior. |13| Authority | Reversible local: writes only temporary transcript or profile artifacts under a system temp directory and may spawn local PTY sessions; rollback is terminating the PTY process and removing its runtime scratch. No remote mutation. No source or VCS mutation. No credential or paid mutation. |14| Side effect | Runs temporary terminal sessions and captures evidence. |15| Done | A deterministic transcript or profile proof artifact exists and the live PTY session is terminated with its runtime scratch removed. |1617## Inputs1819- The CLI/TUI binary or command to exercise (must be supplied).20- The exact reproduction steps, profile target, or verification scenario (must be supplied).21- Optional: expected output, timeout, and environment variables.2223## Procedure24251. Create a fresh session directory under the system temp path for the captured artifact and PTY/tmux runtime scratch. Record the directory for cleanup. Done when: the session directory is created and recorded.262. Spawn the target CLI/TUI under a PTY, or a tmux session attached to a PTY, so interactive behavior is observable. Apply one action per observation: send one input, then capture the full terminal render before sending the next. Done when: the PTY or tmux session is spawned and interactive behavior is observable.273. For reproduction: drive the supplied steps in order, appending the terminal state after each action to the transcript artifact. Done when: every step is driven in order and the transcript artifact captures the terminal state after each action.284. For profiling: run the target under the chosen profiler, capturing timing or allocation output into the profile artifact. Done when: the profile artifact captures timing or allocation output.295. For verification: exercise the scenario, compare the observed output against the expected output when supplied, and record the pass or fail classification in the transcript artifact. Done when: the pass or fail classification is recorded in the transcript artifact.306. Terminate the PTY process, or detach and kill the tmux session. Done when: the PTY process or tmux session is terminated.317. Remove the PTY/tmux runtime scratch (pipes and sockets); the captured transcript or profile artifact file remains as the retained proof. Done when: runtime scratch is removed and the artifact file remains.3233## Failure and recovery34- PTY spawn failure or binary not found: record the error in the transcript, do not invent output, and return blocked with the spawn error.35- Timeout: terminate the PTY process, append the partial transcript up to the timeout, and return blocked with the timeout boundary.36- Non-deterministic output: run a second capture, record the observed variance, mark the proof non-deterministic, and return blocked rather than asserting a false pass.37- Any failure: terminate the PTY or tmux process and remove its runtime scratch before returning; if no artifact was captured, delete the whole temp session directory. Never swallow errors or claim the done predicate holds when the proof is missing or inconclusive.3839## Output40Transcript or profile artifact containing captured terminal evidence, plus final classification: reproduced, profiled, verified-pass, verified-fail, blocked, or non-deterministic. Live PTY session terminated and runtime scratch removed before return.
OutlineDriven