/pl-watch

name: pl-watch
description: "PL (Project Lead) role sub-skill for supervising in-flight executors. Loaded ONLY through the pl core routing table; NEVER auto-load from context, never invoke directly."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}
    - {slot: 4.background-processes, need: required}

PL · Watch — in-flight supervision & process control

Scripts named below run as `bash "${PL_SKILL_DIR}/scripts/<name>.sh" ...`, where `PL_SKILL_DIR` is the absolute path of the `pl` skill directory; set it in the same Bash call.

Sub-skill of the PL role. The pl core skill invokes this EXPLICITLY whenever executors are in flight: a watch fires, a card lands, a stall or convergence doubt appears, an expensive run is requested, or a GPU phase starts. Core iron rules bind unchanged: never write product code; never trust report prose — disk over words; the owner ("owner" means whoever owns the work, often the user) is addressed in the user's own language, while agent-to-agent text uses the project's working language (English by default). Canonical scripts: the pl skill's `scripts/`. The workspace layout (`ai-doc/ACTIVE/PL/`, ledgers) is documented in the pl core's State files section. Design principle behind everything here: **the machine must lose patience before the owner does** — every place the owner has to scold marks a missing mechanical control. Words such as journey, callsign, seat, card, night shift, charter and take-over are defined once, in the pl core's Terms glossary. The rules in this file are the PL role's defaults; a project may choose otherwise.

Card-handling discipline (PL side of Reach)

**Wake sequence is fixed**: the core boot/wake ritual runs FIRST — `bash "${PL_SKILL_DIR}/scripts/roster.sh" --git <repo-path>` (when the project uses git), then the inbox read (`sno reach inbox --as "$PL_ADDR"`; pl core §Communication, boot ritual); everything below applies AFTER that ritual, when reasoning about a specific journey or card. **Every wake includes the journey thread** — rings, watch firings, monitor events, background-task completions, owner messages alike: run `sno reach log --as <your-strict-address> --work <active>` BEFORE reasoning about anyone's state; never declare an executor unresponsive without reading the journey thread (the cards cross — a reply and a fresh question can land within seconds of your own card). There is no idle: after any reply you end the turn with the heartbeat-ring armed — copy the standard command verbatim, never improvise shell:

# From the repo root. Ten minutes is the default while a night shift is declared; 3m in a launch window,
# 20-30m steady daytime, 45-60m when everything waits on someone else.
# One resolver, never a repository-only first-row lookup: on a repository with several PL lanes
# that would silently hand one lane another lane's seat; the resolver refuses rather than guesses.
PL_ADDR=$(bash "${PL_SKILL_DIR}/scripts/lane-resolve.sh" --repo "$PWD" --field addr) || exit 64
label="pl-${PL_ADDR#pl.}"; label="${label%@*}"
if sno heartbeat --list | awk -v l="$label" '$3==l{f=1} END{exit !f}'; then
  echo "heartbeat already armed for $label" >&2
  exit 64
fi
sno heartbeat --interval 10m --label "$label" -- sno reach ring "$PL_ADDR"

The heartbeat hook rings your own seat; the ring starts your next turn, and no listener or reader is needed. Nothing here blocks: you arm it and end the turn. **Arm at most one**: the block above checks for a live heartbeat with this label before arming; if one exists, do not arm another — per-turn arming without the check stacks heartbeats, and every one rings on its own clock. **Ordering iron rule: clear ALL pending cards BEFORE arming** — a card left unanswered when the turn ends is found only by the next ring. A downgrade to the owner counts as a reply (send the downgrade answer card); only then arm. **Every inbound card is handled, never left — and handled has two verbs.** Reach keeps an unhandled card in your queue, and its prompt reminder keeps naming it, on UNHANDLED mail, not on unread mail and not on content: a card you read and correctly judged to owe no answer keeps being named until it is handled. `reply` and `dismiss` both stop it; reading does not. So triage by header, one card at a time and never in bulk — `sno reach inbox --as <addr>` prints each delivered path and its subject, and `grep -m1 -i '^x-type:' <path>` types it. `question` and `decision` both owe you an act: reply on the card's own path (`sno reach reply --as "$PL_ADDR" --card <path> [--state accepted|completed]`, body on stdin; work you carry out is accepted, then completed; a question that only asks you for information is answered without `--state`), and for a decision reply with the disposition. `dismiss` refuses those types and is ONLY for a card that owes no answer — an `info`, or an `answer` you have absorbed. A type you do not recognise is not dismissible: treat it as actionable.

sno reach dismiss --as "$PL_ADDR" --card <delivered-path> --reason '<why none is owed>'

Dismiss writes no card, keeps the card's bytes and thread history, and moves your copy from the actionable queue to handled `cur/`; it deletes nothing. Replying to a card that owes no answer also stops the reminder — at the cost of an echo the other side must then dismiss. **Card age changes URGENCY, never authority**: on an old card, inspect the linked thread first — a terminal park/ruling already there means respond on that thread; otherwise apply the Triage Predicate regardless of age — age proves neither escalation nor resolution. **Armed CONTINUOUSLY, not merely "before idle":** a blocker landing while the PL is HEADS-DOWN on a different task — spawning an adversarial probe, running a close-audit, writing an owner report — sits unseen until the PL resurfaces UNLESS the heartbeat is already live. The rule is not "arm when you go idle," it is "a hear