git:20261001.0fd1d23 to git:20261005.793fde4

---

name: mo-qa

description: Run and control Mo QA sessions with Momentic's `qa` CLI. Use for bug bashes, status checks, report export, replies to Mo, file transfer, or repairs based on Mo findings.

---

# Run QA with Mo

Mo runs browser QA in a hosted sandbox. Its files and processes are remote.

## Work while Mo runs

Keep the tested revision stable through the initial QA pass and its

reproductions. Do not change anything the target serves or hot-reloads, restart

the app, deploy to its URL, or mutate shared test data while Mo uses it. Other

work, such as code review, is fine. For isolated bug fixes during a longer run,

follow [Repair loop](references/remediation-loop.md).

Findings arrive through `qa status "$session_id" --full`. A `kind: "bug"`

entry has been independently reproduced. A `kind: "flag"` entry is a static,

single-frame mistake such as a typo, recorded without reproduction. Test-case

verdicts are `verified`, `issues_found`, or `blocked`. When you report a finding

to the user, include its name, evidence, status, and `web_url`.

If Mo is blocked, answer from the brief, repository, or authorized environment

data when you can. Otherwise ask the user for the missing access, permission,

or decision, then send the answer to root Mo. Root Mo relays context to its

internal sub-agents. Never invent or reveal a secret.

## Prepare the brief

Run `qa version`. If Mo is missing or outdated, read

[Installation](references/installation.md). Read

[Authentication](references/authentication.md) after an authentication error.

Use the target from the request. For a local or private target, read

[Tunneling](references/tunneling.md).

3. The login method, test account label, and allowed test data.

4. Prohibited actions and data that Mo must not change.

6. Any non-default browser setup. Read

[Browser settings](references/browser-settings.md) when needed.

## Start the session

```bash

brief=$(cat <<'EOF'

Target: https://preview.example.com/checkout?variant=express

Goal: Keep the selected shipping method after returning from payment.

Sign in: Use the staging QA buyer account.

Test data: Create test carts and orders only.

Do not: Submit payment, send email, delete data, or change the shared catalog.

Coverage: Smoke the express-checkout happy path and standard checkout. Skip other flows and failure states.

Pass criteria:

- The shipping method stays selected.

- The total does not change.

- Standard checkout still works.

EOF

)

session_json=$(qa start "$brief")

session_id=$(jq -r .sessionId <<<"$session_json")

web_url=$(jq -r .webUrl <<<"$session_json")

created_at=$(jq -r '.createdAt // empty' <<<"$session_json")

```

Starting returns before Mo finishes. Preserve these values: every later command

needs `session_id`, the user can watch or join through `web_url`, and

`created_at` records when the session began. `createdAt` can be absent when the

server runs an earlier API version.

A Momentic environment groups a `BASE_URL` with reusable non-secret variables

under a name such as `staging`. `--environment NAME` selects one created under

**Environments** in the Momentic dashboard, not one from the shell or

`momentic.config.yaml`. Mo copies its variables into the session at start.

Use repeatable `--env-file` or `--env-var NAME` options for local values and

secrets; they override matching environment variables. `--env-var` forwards a

variable that is already present in the `qa start` process environment; it does

not accept `NAME=value`. Never put the secret value in the command or brief.

interaction to a human pace when the target needs it.

## Follow the session

```bash

seen=""

while :; do

snapshot=$(qa status "$session_id" --full) ||

{ echo "status request failed"; sleep 30; continue; }

events=$(jq -r '"displayState \(.displayState // .state)",

(.findings.bugs[] | "\(.kind) \(.name)"),

(.findings.verdicts[] | "verdict \(.status) \(.testCaseName // "-")")' \

<<<"$snapshot" | sort)

comm -13 <(printf '%s\n' "$seen") <(printf '%s\n' "$events")

seen=$events

case $(jq -r '.displayState // .state' <<<"$snapshot") in

esac

sleep 30

done

```

In Codex without a runner sub-agent, keep the watcher in the foreground of a

long-running `exec_command`, retain its returned session ID, and drain it with

`write_stdin`. Do not append `&`, detach it, or finish the turn while it runs.

Shell variables do not persist across separate commands, so interpolate the

literal Mo session ID or start the watcher in the same shell that set it.

`displayState` is the session's state as the UI shows it. `status`, `read`,

and `report` all report the same word there:

| State | Meaning |

| ------------------- | ---------------------------------------------------------- |

| `running` | Root Mo is working. |

| `waiting_on_agents` | Root Mo is idle; its internal sub-agents are working. |

| `needs_you` | Mo asked a question. Answer it with `qa send`. |

| `ready` | No agent is running and results are available. |

| `sleeping` | No agent is running and there is no report or final reply. |

| `cancelled` | Work was stopped. |

| `failed_start` | The session never started. Start a new one. |

`sessionState` is the lifecycle state (`starting`, `working`,

across all three commands. `state` is the legacy field, an alias of

`sessionState` wherever it appears. `createdAt` is the session creation time,

and `lastActivityAt` is the last persisted update. `latestTurn` contains the

most recent persisted assistant timing metadata: `startedAt`, `completedAt`,

and `durationMs`. A partial timing uses `null`. Servers running an earlier API

can omit `displayState` on `read` and `report`; use `qa status` for the

display word on those.

Use this bounded read for Mo's questions and replies, not findings:

```bash

qa read "$session_id" --from start --timeout 45s --json

```

`--from latest` also misses a turn that finishes before the read begins. In a

`read` response, `displayState` matches the `status` word, while `state` and

`sessionState` carry the lifecycle state. Servers running an earlier API omit

`displayState`; use `qa status` for the display word on those.

`timedOut: true` means Mo is still working.

With `--json`, `read` writes one JSON response to stdout and no progress text.

Without `--json`, a read that waits longer than two seconds prints liveness to

stderr. Returned messages stay on stdout, while timeout or stopped status text

stays on stderr.

`qa wait "$session_id" --json` returns when root Mo's turn finishes, stops, or

needs input. Exit code `2` means Mo needs input; `4` means it was stopped.

Internal sub-agents can still be running, so confirm `qa status` reports

`ready` or `sleeping` before treating the session as done.

Never send a message to ask for progress. Use `status`, `read`, or `wait`.

Send only to answer a blocker or deliberately steer or recheck work. Prefer to

send while Mo is idle or waiting:

```bash

qa send --session-id "$session_id" --wait 45s "Use the staging account."

```

Sending while active stops root Mo's current turn and in-flight tool call. Do

that only when the new direction should take priority. Without `--wait`, confirm

the reply with `read`.

## Finish or repair

Before presenting final results, read [Reports](references/reports.md). Confirm

If the user asked for fixes, read

[Repair loop](references/remediation-loop.md). Otherwise, do not change app code.

Choose how to stop:

- `qa stop <session-id>` interrupts root Mo only. Sub-agents keep testing,

filing findings, and billing. Root Mo stays stopped until your next

`qa send`. Use it to redirect Mo without losing in-flight tests.

- `qa stop <session-id> --subagents` also stops every running sub-agent. Use it

to end spending. `qa send` can still resume the session.

- `qa archive <session-id>` cancels all work, hides the session, and rejects

further `qa send`. Unarchive is web-only.

`qa upload` returns a sandbox path. Send that path to Mo because local paths do

not exist in its sandbox. Create the destination directory before `qa download`

when `--output` names a directory. Run `qa <command> --help` for syntax.

## Fallback: provide source context without repository access

Prefer setting up Git access in Mo for repository context. If access is

unavailable, tell the user and recommend configuring it.

When Git access cannot be configured, prepare a temporary source snapshot

containing only the files Mo needs. Review its contents before uploading;

exclude `.env` files, credentials, private keys, tokens, `node_modules`, build

output, and unrelated customer data. Include relevant local changes or a

reviewed patch when testing uncommitted work.

After starting the session, upload the snapshot with `qa upload` and send Mo

the returned sandbox path with `qa send`. Remove the temporary local snapshot

after upload. Tell Mo to use it as read-only context, which paths are

authoritative, whether it represents baseline or modified code, and which

commands or dependency files explain how to use it. Local paths do not work

inside Mo's sandbox.