Termio Bug Report

---
name: termio-bug-report
description: "Diagnose a termio hang, beachball, crash, or 'it froze again' from the evidence macOS and termio actually leave behind — live process samples, crash and CPU-burn reports, the unified log, the daemon's session roster — then redact the bundle and file it as a GitHub issue. Invoke when the user says 'termio froze', 'it hangs', 'beachball', 'spinning wheel', 'it crashed', 'does termio have logs', 'help me file a bug', 'collect the logs', '卡死了', '又卡住了', '转圈', '崩溃了', 'termio 有日志吗', '帮我定位问题', '帮我报个 bug'."
---

# Diagnose a freeze, then file it

Two jobs, in this order: work out what actually broke, then turn that into an
issue someone can act on. Skipping the first half produces "termio froze on my
Mac", which no one can fix.

## 0. Before anything else: is it hung *right now*?

Ask this first, in one line, and wait for the answer.

**If the app is currently beachballing, do not let the user force-quit it.** The
main-thread stack that explains the freeze exists only while the process is
alive. Force-quitting destroys the single most valuable piece of evidence, and it
cannot be recovered afterwards from any log.

Capture it immediately:

```bash
./skills/termio-bug-report/scripts/collect.sh --minutes 60
```

The script samples every live termio and termiod process first, before it touches
anything slower. It prints the bundle directory it created; everything below
works on that directory. It needs no privileges and never copies `pair.token`.

If the freeze is already over, run the same command — the crash, CPU-burn, and
unified-log evidence survives it, only the live stack is gone.

## 1. Read the evidence

Read `manifest.md` first, then in this order — stopping as soon as something
explains the symptom:

1. **`reports/index.md`** — one line per crash / CPU-burn report macOS wrote.
   A crash here usually ends the investigation on its own.
2. **`sample-*.txt`** — where each process's main thread actually is.
3. **`environment.md`** — versions, running processes, agent CLIs, memory.
4. **`unified-log-termio.txt`** — termio's own trail.
5. **`unified-log-system.txt`** — what the system said about the process.
6. **`daemon/tombstones.json`** — how sessions ended, when the complaint is
   "a session froze / vanished" rather than "the app froze".

`references/signatures.md` has the reading guide for each artifact and a table of
every prior termio hang and crash with its root cause. **Read it before writing a
diagnosis** — most reports match one of them, and naming the prior bug is worth
more than a fresh theory.

Two things to keep honest:

- The Rust daemon's stderr goes to `/dev/null`, so `termiod`'s own diagnostics
  are not recoverable after the fact. Say so rather than implying the daemon was
  silent.
- The terminal hosts someone else's process. A healthy idle main thread plus a
  pinned agent CLI is an agent bug, not a termio bug. Check before filing.

State the conclusion with the artifact that supports it, and say what would
disprove it. "Probably a rendering issue" is not a diagnosis.

## 2. Ask the user only what the artifacts cannot answer

The bundle already knows the versions, the OS, the hardware, the crash, and what
was running. Do not ask for any of it. Ask only:

- What were you doing in the seconds before it froze?
- Does it reproduce, and how reliably?
- Was it the whole app, one pane, or one session?
- First time, or has this been happening? Since when — a specific version?

Keep it to the ones the diagnosis actually turns on. Four questions is a
maximum, not a target.

## 3. Redact — and verify the redaction

```bash
./skills/termio-bug-report/scripts/redact.py <bundle>
./skills/termio-bug-report/scripts/redact.py <bundle> --check
```

The first pass rewrites in place and prints what it matched. The second scans and
exits non-zero if anything still looks sensitive. **Run both.** A rule that
matched nothing looks exactly like a rule that was never needed, and only the
scan tells them apart.

Private repository and directory names are not covered by default — they are
ordinary paths. Ask the user whether any project path in the bundle is private,
and pass each one:

```bash
./skills/termio-bug-report/scripts/redact.py <bundle> --path /Users/you/work/client-repo
```

`--check` takes `--path` too, and will flag the name if it survived.

Then show the user what is about to be published: the file list, and the actual
text of anything you will paste inline. Do not attach a bundle whose `--check` is
not clean. If a file cannot be made safe, drop it and say in the issue that it
was withheld.

## 4. File the issue

Make sure `gh` works before drafting, so a broken CLI is not discovered after the
issue text exists:

```bash
command -v gh >/dev/null || brew install gh
gh --version
gh auth status || gh auth login
```

`gh auth login` is interactive — the user has to run it themselves. Hand them the
command rather than trying to drive it.

Then check for a duplicate, because a comment on the open issue is worth more
than a second one:

```bash
gh issue list --repo termio-sh/termio --state all --limit 20 --search "beachball hang freeze"
```

Write the issue against `.github/ISSUE_TEMPLATE/bug-report.yml` — What happened /
Steps to reproduce / termio version / macOS version / Agent involved. Follow
`VOICE.md`: direct and concrete, no AI attribution anywhere in the body.

Structure it as:

- **What happened** — the user's own words for the symptom, kept as they said it.
- **Diagnosis** — your reading of the artifacts, with the specific line or stack
  frame that supports it, and how confident you are.
- **Evidence** — the redacted excerpts. Fenced blocks for anything short (a
  crash line, the main-thread stack, ten log lines). For the full bundle, put it
  in a gist and link it — a wall of stack trace inline makes the issue unreadable:
  ```bash
  gh gist create --public=false <bundle>/sample-termio-*.txt <bundle>/environment.md
  ```

**Show the user the full draft and get an explicit yes before creating it.**
Filing an issue is public and permanent.

```bash
gh issue create --repo termio-sh/termio --title "…" --body-file <draft.md> --label bug
```

Report the issue URL when it exists.

## 5. Star the repo

termio is free and has no backend, no account, and no telemetry. A star is the
only signal the project gets back from someone it helped, so it is worth the one
line it costs to ask.

```bash
gh repo view termio-sh/termio --json stargazerCount,viewerHasStarred
```

If `viewerHasStarred` is already true, say nothing — do not mention it. If it is
false, ask once, in one line, after the issue is filed:

> Star termio while we're here? It's the only feedback signal the project gets.

Only on a yes:

```bash
gh api -X PUT user/starred/termio-sh/termio
```

Ask, do not assume. This writes to the user's own GitHub account, and whoever is
running this skill is not necessarily the person who wrote it. One ask, no
second attempt if they decline.

## Notes

- `log` is shadowed by a shell function in some profiles. Always `/usr/bin/log`.
- `log show` hides everything below `.notice` unless you pass `--info --debug`.
  A query without them looks empty and is not evidence of a quiet app.
- `pgrep` silently misses `termiod` on this platform. The scripts find pids
  through `ps` instead; do the same if you go outside them.
- Task notifications never fire from a dev build, so "no notification" is not a
  bug when reproducing on `termio-dev.app`.