# MOST Control — AI Agent Runbook

Use this runbook when an AI coding agent works on a real computer through MOST Control.

## Core rule

**Source of truth is the actual device/workspace/files/Git/tests/running app. Model assumptions, a successful command, or a visible process are not evidence by themselves. For device setup, the minimum proof is a confirmed online heartbeat.**

## READ-ONLY FIRST

1. Run `devices_list` and select the intended device unambiguously.
2. Run `device_health`, then check `coding_mode` and enabled capabilities.
3. Locate the project root. Do not edit yet.
4. Run `open_workspace` in reusable `checkout` mode or an isolated Git `worktree` when isolation is useful.
5. Read applicable `AGENTS.md` / `CLAUDE.md` and relevant Agent Skills discovered for the workspace.
6. Run `workspace_provenance`.
7. Run `workspace_doctor`.
8. Check `git status`, current branch and recent commit from the workspace.
9. Identify stack, entry points and real test/lint/build commands.
10. Report a short **VERIFIED SUMMARY** and the smallest reasonable plan.

## If the device is offline

1. Use the first-party MOST Repair path and re-check device health before any deeper recovery action.
2. Re-check `devices_list` and `device_health`.
3. Prefer the first-party **Repair** action on the exact offline device:
   - Windows: verified components + watchdog + relay + heartbeat;
   - macOS: backup/rollback + LaunchAgent + relay + heartbeat;
   - Linux: backup/rollback + systemd + relay + heartbeat.
4. If Repair is unavailable, use local first-party diagnostics:
   - Windows: `%LOCALAPPDATA%\GPTMost\START-MOST.cmd`;
   - macOS: `launchctl print gui/$(id -u)/com.mostcontrol.relay`;
   - Linux: `sudo systemctl status most-control-<user>.service`.
5. Re-check health/capabilities after recovery.
6. If state remains ambiguous, stop editing and report facts/logs.

## Editing rules

- Make the smallest correct change.
- Do not overwrite unrelated uncommitted user changes.
- If Git is dirty, identify existing changes before touching overlapping files.
- Prefer validated `apply_patch` for source edits.
- Verify after each logical block.
- Before finishing, use `show_changes`.

## Verification ladder

| Change | Minimum evidence |
| --- | --- |
| Code | diff + targeted test |
| Bug fix | reproduce → regression test → fix → re-check |
| Refactor | behavior before/after + relevant suite |
| Build | successful build + artifact exists |
| API | real request → expected status/body |
| UI | real browser/screenshot + console/network state |
| Git delivery | clean status + commit SHA + remote SHA if pushed |
| Deploy | immutable SHA/version + live health/readback |

## Do not do unless it is explicitly within the user's task

- push / merge / deploy;
- destructive migrations;
- deleting databases/files/buckets/users;
- rotating or exposing secrets;
- broadening MOST device capabilities;
- mass external messages/payments.

If delivery/deploy is explicitly requested, do it safely with rollback/readback where appropriate.

## Secrets

Never print or commit full `.env`, API keys, access/refresh tokens, device/Runner tokens, cookies, SSH private keys or database passwords.

## Default Git workflow

```text
git status
↓
understand branch/worktree and existing changes
↓
isolated worktree when useful
↓
small patch
↓
targeted verification
↓
relevant full verification
↓
show_changes / git diff
↓
commit/push/deploy only in requested scope
↓
live readback + clean state
```

## Error protocol

A failed command is not a reason to retry randomly.

1. Read stdout/stderr.
2. Check actual workspace/Git/process state after the failure.
3. Name one concrete likely cause.
4. Fix the smallest cause without expanding scope.
5. Repeat the relevant check once.
6. If state is still ambiguous, stop and report facts.

## Final report

```text
Сделано:
- ...

Проверено:
- source of truth → result

Не проверено:
- ...

Следующий шаг:
- ...

Риски / блокеры:
- ...
```

## FINISH

“Code was written” is not FINISH.

FINISH = the requested result exists + relevant checks passed + observable behavior was verified + remaining risks are stated honestly.