Command Center

The OSTwin terminal command center is the operator-facing CLI surface for plan runs and war-room inspection. It is designed to be quiet by default, scriptable when needed, and reversible during rollout.

Repository-local source references are kept in the repo for maintainers: the source product design is .agents/GUI-plan.md, and the implementation plan is .agents/plans/GUI-terminal-command-center-plan.md. These are not public docs pages; use them only when working inside this repository, and keep public docs aligned to the supported CLI behavior described below.

Run modes

Use ostwin run <plan> for plan execution. The command chooses the safest output mode for the current terminal.

Mode	Command or trigger	What to expect	Best for
Quiet live command center	`ostwin run PLAN.md` in an interactive, capable terminal	A stable command-center frame with plan overview, room table, and recent agent flow. Raw logs are not streamed into the main view.	Human operators watching a run
Plain	`ostwin run PLAN.md --plain`	Copy/paste-friendly lifecycle lines and final summary, no full-screen redraw.	CI logs, screen readers, terminals that do not render TUI well
JSON events	`ostwin run PLAN.md --json-events`	Newline-delimited JSON event objects on stdout, or empty stdout when a dry run emits no events. Human diagnostics go to stderr.	Scripts and event consumers
Debug	`ostwin run PLAN.md --debug`	Raw diagnostic logging is enabled (`OSTWIN_CONSOLE_LOG_LEVEL=DEBUG`, `AGENT_OS_LOG_LEVEL=DEBUG`).	Troubleshooting runner/manager behavior
No color	`NO_COLOR=1 ostwin run PLAN.md`	Styling is disabled. If the terminal is otherwise interactive, live layout may still render without color; use `--plain` for a fully linear alternative.	Accessibility and copy-safe terminals
CI/non-TTY fallback	`CI=true`, redirected stdout, `--non-interactive`, small/unsupported terminal	Plain mode is selected automatically.	Automation and unsupported terminals

Quiet output, debug output, and raw logs

Default terminal output is intentionally quiet: normal lifecycle state changes are visible, but polling diagnostics and role-launch internals are hidden from the main screen.
--debug turns diagnostic log levels back up for the run. Use it when you need runner arguments, spawn decisions, or manager-loop details.
Raw logs are still written to files and remain available outside the live renderer. Use ostwin room <room-id> logs --last 200, ostwin room <room-id> logs --full, or direct file access for post-mortems.
Full channel message bodies are available with ostwin room <room-id> messages --full or as machine-readable JSON with ostwin room <room-id> messages --json --full.

Read-only inspection commands

These commands read the current runtime files. They do not start agents.

Command	Purpose	Useful flags
`ostwin rooms`	List rooms in the current run state.	`--json`
`ostwin room <room-id>`	Show one room summary with detail sections.	`--json` on summary
`ostwin room <room-id> brief`	Print `brief.md`.	`--full`, `--last N`, `--json`
`ostwin room <room-id> tasks`	Print `TASKS.md`.	`--full`, `--last N`, `--json`
`ostwin room <room-id> qa`	Print `QA.md`.	`--full`, `--last N`, `--json`
`ostwin room <room-id> messages`	Show channel message cards or full bodies.	`--full`, `--last N`, `--json`
`ostwin room <room-id> logs`	Show discovered room log file.	`--full`, `--last N`, `--follow`
`ostwin room <room-id> artifacts`	List room artifacts.	`--json`
`ostwin room <room-id> status`	Show current room state.	`--json`
`ostwin epic <EPIC-ID>`	Resolve an epic ref such as `EPIC-002` to its room, then run the same room subcommands.	Same as `room`
`ostwin events`	Render the structured event stream as a timeline.	`--json`, `--last N`, `--follow`
`ostwin timeline`	Alias for `events`.	Same as `events`
`ostwin inspect`	Print current read-only inspection help.	none

Examples:

ostwin rooms --json
ostwin room room-002
ostwin room room-002 messages --full --last 10
ostwin room room-002 logs --last 200
ostwin epic EPIC-002 qa
ostwin events --json --last 50
ostwin timeline --last 20

Runtime files behind room detail sections

The room detail screen is a projection over files in the active war-room root. The root is selected from WARROOMS_DIR when set; otherwise it defaults to <project>/.war-rooms and resolves the newest plan-scoped directory containing room-* folders. OSTWIN_EVENTS_PATH overrides the event stream path.

Detail section	Backing files
Header, state, role, retries, runtime	`config.json`, `progress.json`, `lifecycle.json`, `status`, `retries`, `state_changed_at`, `task-ref`, `pids/*.pid`
Brief preview	`brief.md`
Tasks	`TASKS.md` checklist lines
QA status	`QA.md` and latest QA/pass/fail messages in `channel.jsonl`
Latest messages	`channel.jsonl`, rendered through the agent message card renderer when available
Artifacts	`artifacts/**` file metadata
Logs	First available candidate among `room.log`, `agent.log`, `logs/room.log`, `artifacts/room.log`, `artifacts/<room-id>.log`, `artifacts/room-output.log`, or the first `artifacts/*.log`; falls back to `<room>/room.log` as the expected path
Events/timeline	`<war_rooms_dir>/events.jsonl` or `OSTWIN_EVENTS_PATH`

Search runtime evidence

ostwin search <query> performs a bounded, read-only search across runtime evidence. It currently searches brief.md, TASKS.md, QA.md, channel.jsonl, the discovered room log, artifact metadata, and events.jsonl.

ostwin search "manager triage"
ostwin search "qa failed" --limit 50
ostwin search "smoke-sentinel" --json

Search is intentionally bounded to protect active runs: it reads recent/logical runtime evidence, not every file in the project workspace.

Audited controls

Plan-run controls live under ostwin control .... This is separate from ostwin stop, which still stops dashboard/channel processes.

Command	Current behavior
`ostwin control pause --reason TEXT --yes`	Writes `<war_rooms_dir>/.paused` and emits `operator.plan.pause`; the manager spawn gate observes this marker.
`ostwin control resume --yes`	Removes `.paused` and emits `operator.plan.resume`.
`ostwin control stop --reason TEXT --yes`	Writes `<war_rooms_dir>/.stop-requested` and emits `operator.plan.stop` for graceful manager shutdown.
`ostwin control rerun <room-id> --reason TEXT --yes`	Writes `<room>/requests/rerun-current-role.json` and emits `operator.room.rerun`. The marker is intentionally non-bypassing: manager/lifecycle accounting remains authoritative.
`ostwin control kill <room-id> --role ROLE --reason TEXT --yes`	Emits `operator.room.kill`, then kills/removes the matching PID only after confirmation and reason capture. Stale PID files are removed in the target room.
`ostwin control force-transition <room-id> --to STATE --reason TEXT --yes`	Emits `operator.room.force_transition`, validates the target state against `lifecycle.json` when available, then updates `status`, `state_changed_at`, and `audit.log`.

Safety rules:

Risky controls default to No.
Non-interactive contexts (--non-interactive, redirected input, or CI) fail closed unless --yes and a non-empty --reason are present.
Controls emit structured audit events before mutating room process/state files where applicable.
UI shortcuts must not bypass this CLI validation path.

Terminal limitations and fallbacks

Live rendering is conservative. It falls back to plain output when stdout is redirected, CI=true, --non-interactive is set, the process is not interactive, TERM is empty/dumb/unknown/emacs, or terminal dimensions are too small for a stable layout.

Use these fallbacks when output looks noisy or inaccessible:

NO_COLOR=1 ostwin run PLAN.md
ostwin run PLAN.md --plain
CI=true ostwin run PLAN.md --plain --non-interactive
ostwin run PLAN.md --json-events > events.ndjson

Do not rely on color alone to interpret state. Plain mode and JSON inspection commands carry text labels for status, room IDs, epic refs, and event types.

Rollout and reversibility

The command center is additive. Existing room files, raw logs, JSON status paths, and dashboard flows remain the runtime authority. If a terminal cannot use the live renderer, switch to --plain, NO_COLOR=1, CI=true, or read-only inspection commands. The source design explicitly preserves raw logs and machine-readable output as fallback paths.

Non-goals and compatibility commitments

Current command-center rollout does not replace the manager loop, dashboard plan APIs, web dashboard, room lifecycle authority, or raw logs. It also does not make events.jsonl the source of truth for orchestration decisions; events are an observational timeline/audit feed.

Compatibility commitments for EPIC-001 through EPIC-007:

Existing ostwin status --json, rooms --json, and other machine-readable outputs must remain parseable and free of human banners.
ostwin stop keeps its existing dashboard/channel shutdown meaning.
ostwin control ... is the only namespace for audited plan-run controls.
Plain and JSON event modes must remain available even if live rendering is disabled or rolled back.
Raw room/channel/log files remain accessible for post-mortems and scripts.