watchtower

name

watchtower

description

Use when the user wants an agent session supervised while they are not watching it. Triggers on "launch this and watch it", "keep an eye on that session", "drive this to done while I'm out", "what are my sessions waiting on", or any task long enough that the user will not sit through it. Launches a supervised session, reports what is live and what each one is blocked on, and puts a driver on one session that answers routine prompts and escalates every real decision to the user.

Watchtower: supervising a session the user is not watching

A long session needs a human a handful of times, for seconds each, and the user cannot predict when. So they either sit and watch a progress bar or come back to a session that stopped twenty minutes in on a permission prompt. Watchtower is what sits in that chair: it launches a session that is addressable, puts a driver on it, and gets the user back only for the things that are actually theirs to decide.

Read the charter before driving anything

PATTERN.md is the charter: the roles, the reasoning, and every authority boundary. Read it before you launch, seed, or drive a session. It is not restated here, and it is deliberately not summarized here either. Two copies of an authority boundary drift, and a drifted boundary is the failure this tier exists to prevent.

The one line worth carrying before you get there: the routine belongs to this tier, every choice belongs to the user, and when you cannot tell which one you are looking at, it is a choice.

When not to use this

• The user is sitting right there watching the session. Then they are the driver, and a second supervisor is pure overhead.
• The task is short. If it finishes before the user could get up, the setup costs more than it saves.
• The session already exists. Watchtower only drives sessions it launched, because a session it did not launch has a goal and stop conditions it was never told. Report on those; do not adopt them.

Preflight

Run `bin/gucci-doctor` before the first launch in a session. It checks the tier's dependencies and says plainly what is missing. If it fails, report exactly what it said and stop. Do not launch, do not work around it, and do not diagnose it three commands deep into a broken session.

Dependencies: tmux and python3 >= 3.9. Tested on macOS. Linux probably works and is unverified; Windows is not supported.

Entry points

Path	What it is
PATTERN.md	The charter. Roles, boundaries, limits. Read first
bin/gucci-doctor	Preflight. Run before the first launch
bin/agent-solo	Launch a session that is addressable from birth. The only supported way in
bin/wt-send	Send one line into a session and verify it landed
bin/wt-status	What is live, and what each session is waiting on
.claude/agents/wt-driver.md	The driver. Babysits one session to a verified result
lib/sessions.py	The single place the session registry is parsed

The loop

1. Preflight once, per the gate above.
2. Launch with bin/agent-solo. Keep the target handle it reports; the driver needs it.
3. Seed the session with bin/wt-send: goal, constraints, and what "verified done" concretely means.
4. Spawn a wt-driver immediately, with the target, goal, constraints, and verification criteria. Those four things are its whole brief. Never hand it state about any other session.
5. Handle its returns. A driver ends its shift on an escalation, on a verified result, or at its shift cap. On an escalation, put the question to the user unanswered and arm a fresh driver with their decision as context. On an interim report, arm a fresh driver with that report. Relay its sends to the user as if they were your own.

Then stop touching the session. Polling it yourself is the job you just delegated.