Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
Trigger nodes (issue #493)
A trigger is a first-class canvas node that fires a payload into a connected terminal/agent
node on a schedule — the canvas owns the schedule, unlike the ephemeral /loop /schedule
/cron cards, which visualize recurrence an agent set up inside its own process. Landed in four
phases: schema + arm store (#502), scheduler (#523), delivery (#595), UI (this one).
Trust model (the part everything else follows from)
The trigger's definition (schedule cron | interval | once, payload, target node id, note)
lives on the node in .nodeterm/project.json — git-shared on purpose, and therefore HOSTILE
input: sanitized on every load path (sanitizeNodeTriggers, @shared/trigger), rebuilt
known-fields-only, malformed ⇒ an inert node.
The consent to fire is machine-local and content-bound: core/trigger-arm-store.ts records
canonicalTriggerSpec of the exact content the user armed, and isArmed answers true only while
the node's current spec canonicalizes to the same string. Consequences, all test-pinned:
- a trigger arriving via
git clone/pullis disarmed until someone on this machine arms it; - editing the schedule/payload/target — locally or via a pull — lands an armed trigger back in
disarmed (
CHANGEDon the card), never runs the new content under the old consent; - disarming (or editing) while a payload waits in the deliver-on-idle queue drops it at flush.
The machine (all core, both shells)
startTriggerService (core/trigger-service.ts) composes everything once; desktop main and the
Server Edition boot the identical call — a headless SE fires with no browser tab open.
- Scheduler (
core/trigger-scheduler.ts): 30 s sweep, fire-timeisArmedre-ask, no catch-up (a host that slept through three slots fires once, from now; a spentoncelogs a single honestmissed), exactly-once per slot. Cron is the dependency-free@shared/cron(five fields, names, steps, vixie dom/dow OR rule, local wall-clock; parse failure schedules nothing). - Delivery (
core/trigger-delivery.ts): thesendTextpaste path (paste-buffer -p, payload by stdin). An agent target delivers only on the mirror's idledone; working/blocked/unknown queue in a trigger-localDeliveryQueueinstance (TTL 5 min) flushed by the mirror'sdoneedge, with full flush-time re-validation. A plain-terminal target delivers only into a shell-owned pane and never queues. A dead target is amissed, never a cold start. - IPC (
triggers:arm/disarm/status/run-now, registered inside the service):armbinds the spec the renderer displayed (consent = what was seen);run-nowtakes no spec — the payload is resolved core-side from the node's persisted content, so a caller chooses when, never what. All inputs re-validated at the boundary.
The card (renderer/nodes/TriggerNode.tsx, decisions in renderer/lib/triggerCard.ts)
Schedule line + live next-run countdown, target (plus a derived, never-persisted edge), payload
preview, note, and an honest state chip: ARMED / DISARMED (with the "definitions travel with
the project; arming is always a local decision" narrative) / CHANGED (armed for other content)
/ SET UP (no valid spec — the editor opens). Arming passes a ConfirmDialog whose body shows the
exact schedule + payload + target being consented to; Run-now on a disarmed trigger confirms the
same way. The last runs render from the core's ring: fired, delivered-late, queued,
missed, failed, expired.
Surfaces
- Desktop + Server Edition: identical (core service + real ws-bridge namespace).
- Relay tabs: the stub refuses — the arm store and sessions live on the host, and arming from a guest would write another machine's execution consent. The card says so.
- Mobile: N/A (no canvas). The kanban board deliberately shows no trigger cards in v1: a trigger is configuration, not work-in-flight, and its target session already has a card — made as a conscious three-surfaces call, revisit if boards grow a configuration lane.
- Host-alive v1 (the #493 design decision): nothing fires while the app is closed, and missed fires are logged, never retroactively run. The durable answer is a Server Edition host; OS-level scheduling (crontab/launchd/Task Scheduler) is a possible v2 as an explicit, reversible per-trigger opt-in — the #490 consent invariant applies in full.
Device checklist (owed — written where it could not be run)
- macOS: create → edit → arm → scheduled fire into an idle claude node; verify the payload
arrives framed (no submit-per-line) and the run ring shows
fired. - macOS: fire while the target is mid-turn →
queued, thendelivered-lateon turn end; disarm while queued → dropped. - Server Edition (browser): same arm/fire round trip; then close the tab and verify a scheduled fire still lands (headless firing).
- Relay tab: the card shows the managed-on-host notice, no dead buttons.
- Fall-back DST hour + spring-forward hour behavior of a cron trigger (documented edges).