ntm

What this skill does

<!-- TOC: One Rule | Cold Start | Mandatory Loop | NTM Action Card | Command Selection Matrix | Pattern Tiers | Anti-Patterns | Pre-Flight Checklist | Quick Start | Mental Model | Session Orchestration | Dispatch & Reusable Assets | Work Intelligence | Coordination | Safety | Robot Mode | Controller Agents | Serve API | Project Resolution | Gotchas | References | Related Skills -->

> **Scope:** this skill is the **NTM tool reference** — every verb, flag, schema, and integration point. For operator loops, marching orders, unstick ladders, swarm anti-patterns, and tending cadence, use the companion `vibing-with-ntm` skill.

# NTM — Named Tmux Manager

> **The One Rule:** Discover the live NTM contract first, then use the least interactive surface that can prove and execute the action. No `--robot-capabilities` / `--robot-snapshot` evidence -> no automation assumption.

## Outcome — When an NTM Action Has Delivered

A state-changing NTM action is complete only when **all** of the following hold:

- The intended state transition is **visible in `ntm --robot-snapshot`** — not just acknowledged by the command's exit code. (NTM commands can succeed at the API layer while panes/work/locks remain unchanged; trust the snapshot, not the return value.)
- The **attention feed** (`--robot-attention` / `--robot-tail`) shows the expected event(s) — pane output, work-graph movement, lock acquire/release, mail delivery. Absence is evidence of failure.
- Adjacent state (git, br/beads, mail, pipelines) reflects the action's downstream effects within one observation window — otherwise the action fired in isolation and likely didn't accomplish its real purpose.
- Locks and pipelines you opened are either **released / completed** by you, or explicitly handed off via mail with a thread the next operator can claim. Orphaned locks block the swarm.
- For dispatched marching orders: the targeted pane has acknowledged (printed the order, started the work, or replied via mail). A sent-but-not-acknowledged order is not "done."

If the snapshot or attention feed disagrees with what the command said happened, **trust the snapshot** and re-discover the contract — the local model of NTM is stale.


## Cold Start: Which NTM Skill?

If you are coming in fresh, pick the narrowest starting point:

| Situation | Start here |
|---|---|
| You need exact NTM command syntax, robot flags, schemas, or failure-mode fixes | This skill |
| You are tending an already-running swarm and deciding whether to nudge, restart, stand down, or dispatch marching orders | `/vibing-with-ntm` |
| You are running a Brenner-style hypothesis investigation or incident RCA through NTM panes | `brennerbot-with-ntm` |
| You only need Beads or BV mechanics | `/beads-br` or `/beads-bv` |

For any state-changing action, read just enough of this file to choose the command, then verify the live contract with `ntm --robot-capabilities` before executing.

## The Loop (Mandatory)

```
1. DISCOVER   -> ntm --robot-capabilities; ntm --robot-tools; repo AGENTS.md/README.md
2. SNAPSHOT   -> ntm --robot-snapshot; inspect sources/degraded_sources, cursor, sessions, panes
3. SELECT     -> choose the smallest surface: work/assign/send/wait/pipeline/locks/mail
4. PROVE      -> fill the NTM action card: target, contract, safety, ownership, rollback
5. EXECUTE    -> prefer --robot-* for automation; avoid human-only TUIs
6. VERIFY     -> attention/events/causality/tail plus git/br/mail evidence changed as expected
7. CLEANUP    -> release/renew locks, checkpoint/handoff, prune old pipeline state when appropriate
8. REPEAT     -> re-snapshot on cursor expiry or after any state-changing action
```

The most common NTM mistake is treating it like a tmux macro runner. Current NTM is a control plane: robot API, attention feed, work graph, locks/mail, pipelines, ensembles, safety, approvals, serve API, and durability all have explicit contracts. Use the contract.

## NTM Action Card

For every state-changing NTM action, be able to answer this before running it:

```markdown
## NTM action: <command>
- Target session/project: <name/path>; resolved by: `ntm config get projects_base` / `ntm quick` / snapshot
- Live contract checked: `ntm --robot-capabilities` contains <flag>; schema/docs checked if unfamiliar
- Evidence before: cursor=<N>; sources=<fresh/degraded>; panes=<count>; locks=<summary>
- Ownership/safety: Agent Mail reservation or worktree policy is clear; user pane inclusion is intentional
- Blast radius: panes/files/sessions affected; destructive/safety/policy approvals required? <yes/no>
- Verification after: <robot event / tail movement / bead state / git change / pipeline status>
- Recovery: <smart restart / interrupt / checkpoint restore / cancel pipeline / handoff>
```

If you cannot fill the card, do a read-only discovery pass first.

## Command Selection Matrix

Score candidate surfaces when several could work:

```
Score = (ContractFit x Observability x Reversibility) / BlastRadius

ContractFit    1-5: exact robot/schema match beats human help text
Observability  1-5: action emits cursor/event/status/causality evidence
Reversibility  1-5: easy cancel/retry/restore/checkpoint
BlastRadius    1-5: one pane/file is low; whole session/process tree is high
```

Pick the highest score. In ties, prefer the surface that produces structured output.

| Need | Best first surface | Usually wrong |
|---|---|---|
| Know what exists | `ntm --robot-capabilities` | `ntm --help | grep` as sole truth |
| Tend a swarm | `--robot-snapshot` -> `--robot-attention` | fixed sleep/poll loops |
| Send machine-driven prompt | `ntm --robot-send=<session>` | `ntm send` when CASS/confirm prompts can block |
| Recover a pane | `--robot-diagnose` -> `--robot-smart-restart` | immediate hard restart |
| Run repeatable phase work | `ntm pipeline run` / `--robot-pipeline-run` | copy-paste manual dispatch |
| Explain what happened | `--robot-causality` + `--robot-events` | pane scrollback only |
| No ready work | `ntm work queue-dry --format=json` | inventing new work without duplicate/source checks |
| Cross-machine continuity | `checkpoint export` / `handoff create` | shipping attention cursors |

## Pattern Tiers

### Tier 1: Safe Read-Only Surfaces

| Pattern | Use | Proof |
|---|---|---|
| Capabilities/schema | Current command contract | Flag + params exist |
| Snapshot | Baseline state + cursor | `sources` / `degraded_sources` reviewed |
| Events/digest/attention | Tending loop | cursor advances or resync command returned |
| Work triage/queue-dry | Work selection | ready/dry status plus warnings |
| Locks list/check | Coordination truth | no conflicting active reservation |

### Tier 2: Reversible Control

| Pattern | Use | Guard |
|---|---|---|
| `--robot-send` | Directed instruction | panes/type/all explicitly scoped |
| `--robot-interrupt` | Stop wrong task | tail proves wrong task/stall |
| `--robot-smart-restart` | Recover stuck pane | refuses active work |
| `ntm assign` | Match agents to beads | ready work and ownership checked |
| `pipeline cancel/resume` | Workflow control | run id and state file confirmed |

### Tier 3: Durable Orchestration

| Pattern | Use | Guard |
|---|---|---|
| Pipelines | Repeatable multi-step work | dry-run first; state captured |
| Agent Mail / locks | Shared edits | reservation lease and thread id |
| Checkpoint / handoff | Recovery/resume | archive exists and metadata matches |
| Serve API | Long-lived integrations | auth mode and local exposure understood |
| Safety / approve / policy | Risk control | token/policy target, not bead id |

## Anti-Patterns (Never Do)

| Bad move | Why it fails | Use instead |
|---|---|---|
| Call `ntm view` from automation | Retiles the human layout and returns nothing useful | `--robot-tail`, `--robot-snapshot`, or `--robot-dashboard` |
| Trust old notes over `--robot-capabilities` | NTM surface changes quickly | Discover first |
| Send to `--all` without naming the user-pane intent | Ca