@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/trigger-config.js

@@ -0,0 +1,417 @@
+/**
+ * Unified trigger config helpers (Epic T "Unify Triggers", ticket T1 — foundation).
+ *
+ * A **trigger** collapses what were two separate config blocks — event **hooks**
+ * (Epic G) and cron **schedules** (Epic D) — into ONE declarative shape over the
+ * existing `startAgentTurn` execution core (design doc `DESIGN-unified-triggers.md`
+ * §2). A trigger is **when** ({@link TriggerWhen}, a discriminated union on
+ * `trigger.type`) + **what** ({@link TriggerRun}, a shared agent-run definition) +
+ * top-level {@link PaddockTrigger.enabled}:
+ *
+ *   - `schedule` → `cron` **xor** `interval` (fired by herdctl's cron engine)
+ *   - `event`    → a known `on` value (`onArchive` / `afterTurn`, fired by the bus)
+ *   - `webhook`  → `path` — **shape reserved only**; NO ingress is wired in T1
+ *     (that is the deferred T6/#311). It validates + persists so the config surface
+ *     is frozen, but nothing fires it.
+ *
+ * This module is the small, PURE surface around that model — deliberately the same
+ * shape as the shipped `hook-config.ts` / `schedule-config.ts` it subsumes, so the
+ * `TriggerService` (foundation) and T2–T5 (schedule tool-scoping, verb collapse,
+ * Triggers tab, sweeper fold-in) build against ONE frozen contract:
+ *
+ *  - {@link PaddockTriggerSchema} — the Zod **discriminated union** validating one
+ *    trigger (`trigger.type` discriminant + the cron-xor-interval / prompt-xor-
+ *    promptFile refinements). Zod (not a hand-rolled sanitizer like its hook/schedule
+ *    ancestors) per the ticket, because the discriminant + xor rules read cleanly as
+ *    one schema and give T3's REST layer structured errors — while the MAP-level
+ *    {@link sanitizeTriggers} keeps the house "drop one malformed entry, don't brick
+ *    the project" semantics its predecessors have.
+ *  - {@link sanitizeTrigger} / {@link sanitizeTriggers} — validate an untrusted
+ *    record / a hand-edited `project.yaml` `triggers` map.
+ *  - {@link triggerToAgentToolConfig} — project a trigger's {@link TriggerRun} onto
+ *    the herdctl agent tool-config fields (for an event/webhook trigger that runs as
+ *    its OWN `trigger-<slug>-<name>` agent), so the grant is enforced by construction.
+ *  - {@link triggersToHerdctlSchedules} — project schedule-type triggers onto the
+ *    herdctl `ScheduleSchema` shape forwarded into the keeper agent's `schedules`
+ *    block (so herdctl's cron engine arms them, exactly as legacy schedules are).
+ *  - {@link triggerPromptFileAbsPath} — resolve a `promptFile` under the project's
+ *    `.paddock/triggers/` dir, rejecting traversal / non-`.md`.
+ */
+import path from "node:path";
+import { z } from "zod";
+/** The trigger kinds. `webhook` is shape-reserved (no ingress in T1 — deferred T6). */
+export const TRIGGER_TYPES = ["schedule", "event", "webhook"];
+/**
+ * The lifecycle events an `event`-type trigger may fire on. `onArchive` is wired
+ * (fired after a chat-archive commits — the Epic G motivating cleanup). `afterTurn`
+ * is a KNOWN value (validation accepts it) reserved for the sweeper fold-in (T5) —
+ * it validates + persists now but isn't emitted until then, exactly as `webhook` is
+ * shape-reserved. Adding a sibling event stays a ~3-line change (new value here + a
+ * payload + one `emit()` at the commit site).
+ */
+export const TRIGGER_EVENTS = ["onArchive", "afterTurn"];
+const PERMISSION_MODES = ["default", "acceptEdits", "bypassPermissions", "plan"];
+/** The dir (relative to a project's working dir) holding keeper-editable prompts. */
+export const TRIGGER_PROMPT_DIR = path.join(".paddock", "triggers");
+/** Default max agent turns for a trigger when its run doesn't set one. */
+export const TRIGGER_DEFAULT_MAX_TURNS = 30;
+/**
+ * The canonical name of the built-in post-turn CURATOR trigger — the sweeper folded
+ * in as the default `event`/`afterTurn` trigger (T5, design §2.1 #4). A project need
+ * NOT declare it: absent, the curator runs with default behaviour (exactly the shipped
+ * sweeper). Declaring a `curate-overview` trigger only CUSTOMISES that default (extend
+ * its prompt, override its model, or `enabled: false` to switch curation off). Resolved
+ * by NAME as a convenience, but recognised structurally by {@link isCuratorTrigger}.
+ */
+export const CURATE_TRIGGER_NAME = "curate-overview";
+// --- Zod schema (the frozen discriminated union) -------------------------------
+/**
+ * The `schedule` variant — `cron` xor `interval`. The xor can't live inside the
+ * discriminatedUnion member (Zod requires plain object members), so the cron-xor-
+ * interval rule is enforced by {@link PaddockTriggerSchema}'s `superRefine`; here we
+ * only shape/trim the two optional timer fields.
+ */
+const scheduleWhenSchema = z.object({
+    type: z.literal("schedule"),
+    cron: z.string().trim().min(1).optional(),
+    interval: z.string().trim().min(1).optional(),
+});
+/** The `event` variant — a KNOWN `on` value (an unknown one fails validation). */
+const eventWhenSchema = z.object({
+    type: z.literal("event"),
+    on: z.enum(TRIGGER_EVENTS),
+});
+/** The `webhook` variant — shape reserved (a `path`); no ingress is wired in T1. */
+const webhookWhenSchema = z.object({
+    type: z.literal("webhook"),
+    path: z.string().trim().min(1),
+});
+/** The discriminated union on `trigger.type` — the heart of the unified model. */
+const triggerWhenSchema = z.discriminatedUnion("type", [
+    scheduleWhenSchema,
+    eventWhenSchema,
+    webhookWhenSchema,
+]);
+/**
+ * The shared agent-run definition (design §2.3) — WHAT a fired trigger does,
+ * identical across every trigger type. `tools` is a deny-by-default allow-list (the
+ * trigger's capability; `[]` = a tool-less curator); `session` selects new-vs-accrete;
+ * the rest mirror the per-agent overrides hooks already carry.
+ */
+const runSchema = z.object({
+    /** Inline prompt (mutually exclusive with {@link promptFile} — enforced below). */
+    prompt: z.string().optional(),
+    /** Git-tracked `.paddock/triggers/*.md` prompt file, read fresh at fire time. */
+    promptFile: z.string().trim().min(1).optional(),
+    /** `new` = a fresh chat each fire; `resume` = one owned accreting session. */
+    session: z.enum(["new", "resume"]).default("new"),
+    /** Optional per-trigger model override (else the keeper default applies). */
+    model: z.string().trim().min(1).optional(),
+    /** Deny-by-default allow-list = the trigger's capability. `[]` = tool-less. */
+    tools: z.array(z.string().trim().min(1)).default([]),
+    /** Recursion bound for internal spawning (reuses B1); 0 = may not spawn. */
+    maxSpawnDepth: z.number().int().nonnegative().optional(),
+    /** Optional permission mode (else inherits the project-agent default). */
+    permissionMode: z.enum(PERMISSION_MODES).optional(),
+    /** Optional max-turns cap (else {@link TRIGGER_DEFAULT_MAX_TURNS}). */
+    maxTurns: z.number().int().positive().optional(),
+});
+/**
+ * The frozen trigger schema: `trigger` (discriminated union) + `run` + `enabled`.
+ * Two cross-field refinements the discriminatedUnion can't express inline:
+ *  - a `schedule` trigger requires EXACTLY ONE of `cron` / `interval`;
+ *  - `run` requires EXACTLY ONE of `prompt` / `promptFile`.
+ *
+ * `enabled` **defaults `false`** — a trigger created programmatically (or via a
+ * hand-edit that omits it) is inert until deliberately switched on (design §2.3,
+ * mirroring the Epic G safe-create default).
+ */
+export const PaddockTriggerSchema = z
+    .object({
+    trigger: triggerWhenSchema,
+    run: runSchema,
+    enabled: z.boolean().default(false),
+})
+    .superRefine((val, ctx) => {
+    if (val.trigger.type === "schedule") {
+        const hasCron = val.trigger.cron !== undefined;
+        const hasInterval = val.trigger.interval !== undefined;
+        // XOR: both or neither is invalid.
+        if (hasCron === hasInterval) {
+            ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ["trigger"],
+                message: "a schedule trigger requires exactly one of `cron` or `interval`",
+            });
+        }
+    }
+    const hasPrompt = val.run.prompt !== undefined;
+    const hasFile = val.run.promptFile !== undefined;
+    // XOR: exactly one of an inline prompt or a prompt file.
+    if (hasPrompt === hasFile) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["run"],
+            message: "`run` requires exactly one of `prompt` or `promptFile`",
+        });
+    }
+});
+// --- validation ---------------------------------------------------------------
+/** A trigger name we're willing to key on (also a safe herdctl agent-name segment). */
+export function isValidTriggerName(name) {
+    return typeof name === "string" && /^[A-Za-z0-9._-]+$/.test(name) && name.length <= 64;
+}
+/**
+ * Validate + normalise one untrusted trigger record into a {@link PaddockTrigger},
+ * or `null` if it's malformed (bad discriminant, both/neither cron+interval, unknown
+ * `on`, both/neither prompt+promptFile, …). Defaults are applied (`enabled: false`,
+ * `session: "new"`, `tools: []`). Unknown fields are stripped (Zod default).
+ */
+export function sanitizeTrigger(raw) {
+    const result = PaddockTriggerSchema.safeParse(raw);
+    return result.success ? result.data : null;
+}
+/**
+ * Sanitise a whole `triggers` map, DROPPING malformed entries and entries with an
+ * unsafe name — so one bad hand-edit can't brick the project's agent registration
+ * (an invalid trigger agent config would throw in `addAgent`). Returns `undefined`
+ * when nothing survives (so it stays absent on disk / off the project record),
+ * exactly like its `sanitizeHooks` / `sanitizeSchedules` ancestors.
+ */
+export function sanitizeTriggers(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [name, val] of Object.entries(raw)) {
+        if (!isValidTriggerName(name))
+            continue;
+        const t = sanitizeTrigger(val);
+        if (t)
+            out[name] = t;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Overlay a PARTIAL trigger update onto an existing trigger, producing an untrusted
+ * record for {@link sanitizeTrigger} to validate — the unified successor to
+ * {@link import("./hook-config.js").mergeHookUpdate}, used by the self-MCP `set_trigger`
+ * tool so an edit that supplies only some fields (the classic being "enable/disable",
+ * an `enabled`-only set — GG-3) preserves everything else rather than wiping it.
+ *
+ * The three parts merge independently:
+ *  - `trigger` (the WHEN discriminant): supplied wholesale or inherited. Because the
+ *    variants carry different fields (`cron`/`interval` vs `on` vs `path`), a partial
+ *    trigger can't be merged field-by-field — so `incoming.trigger` is taken WHOLE
+ *    when the caller supplies one (i.e. re-specifies `type` + its fields), else the
+ *    existing `trigger` is inherited unchanged.
+ *  - `run` (the WHAT): merged field-by-field over the existing run, so an edit that
+ *    touches only `enabled`/`model`/`tools` keeps the rest. `prompt` and `promptFile`
+ *    are MUTUALLY EXCLUSIVE, so supplying one clears the inherited counterpart —
+ *    otherwise switching a file-backed trigger to an inline prompt would leave the
+ *    stale `promptFile` and the merged record would carry BOTH (rejected by the
+ *    schema's prompt-xor-promptFile refinement). Supplying neither leaves the prompt
+ *    source untouched.
+ *  - `enabled`: the supplied value, else the existing flag, else `false` (safe-create).
+ *
+ * A brand-new trigger (`existing` null) starts from the incoming record verbatim
+ * (its `trigger`/`run` must be complete — the schema rejects it otherwise).
+ */
+export function mergeTriggerUpdate(existing, incoming) {
+    // WHEN: a supplied `trigger` (with a `type`) replaces the whole discriminant; else inherit.
+    const trigger = incoming.trigger && typeof incoming.trigger.type === "string"
+        ? incoming.trigger
+        : existing?.trigger;
+    // WHAT: overlay the supplied run fields on the existing run (or {} for a new trigger).
+    const run = { ...(existing?.run ?? {}), ...(incoming.run ?? {}) };
+    const inRun = incoming.run ?? {};
+    // Switching prompt source: one supplied side clears the inherited other, so the
+    // merged run never carries both (which the prompt-xor-promptFile refinement rejects).
+    if (inRun.prompt !== undefined && inRun.promptFile === undefined)
+        delete run.promptFile;
+    if (inRun.promptFile !== undefined && inRun.prompt === undefined)
+        delete run.prompt;
+    const enabled = incoming.enabled ?? existing?.enabled ?? false;
+    return { trigger, run, enabled };
+}
+// --- projection helpers -------------------------------------------------------
+/**
+ * Whether a trigger runs on its OWN scoped `trigger-<slug>-<name>` agent (so
+ * {@link triggerToAgentToolConfig} governs its capability) rather than as the keeper.
+ *
+ *  - **event** → ALWAYS its own agent (Epic G / T1). Its `tools` allow-list IS the
+ *    capability; an empty `[]` means a deliberately tool-less curator.
+ *  - **schedule** → its own scoped agent ONLY when it declares a NON-EMPTY `run.tools`
+ *    allow-list (T2 — the per-trigger tool-scoping this ticket adds). A schedule with NO
+ *    tools inherits the project agent's default toolset by running as the keeper,
+ *    preserving the pre-T2 behaviour (ticket #307: "a schedule with no tools inherits
+ *    the project-agent default"). This is the one asymmetry with events — a schedule's
+ *    empty `tools` reads as "unscoped, run as keeper", NOT "tool-less curator", because
+ *    schedules historically ran with the keeper's full tools and there are no users to
+ *    migrate off that default.
+ *  - **webhook** → reserved (never fired in T1), so it registers no agent.
+ *
+ * The ONE place the keeper-vs-own-agent routing decision lives, shared by the herdctl
+ * agent registration ({@link import("./herdctl.js").HerdctlService.registerTriggerAgents})
+ * and the fire path (`fireTriggerForProject` in `ws.ts`) so arming and firing always agree.
+ */
+export function triggerRunsOnOwnAgent(trigger) {
+    if (trigger.trigger.type === "event")
+        return true;
+    if (trigger.trigger.type === "schedule")
+        return (trigger.run.tools?.length ?? 0) > 0;
+    return false; // webhook: shape reserved, nothing fires it.
+}
+/**
+ * Whether a trigger is the post-turn CURATOR (the folded-in sweeper, T5): an
+ * `event`/`afterTurn` trigger. The curator is SPECIAL — it does NOT run as a generic
+ * `trigger-<slug>-<name>` agent turn. It is tool-less by nature (returns marked text,
+ * Paddock's `SweepService` parses it and writes OVERVIEW.md/CHANGELOG.md), so it is
+ * executed by the SweepService via the project's `sweeper-<slug>` agent, NOT by the
+ * event dispatcher and NOT by its own herdctl agent. Its `run` therefore only tunes the
+ * sweep (prompt extension, model, `enabled`), which is why (unlike every OTHER event
+ * trigger — see {@link triggerRunsOnOwnAgent}) a curator trigger registers NO scoped
+ * agent and is skipped by the generic fire path. This keeps the sweeper's single
+ * dispatch (no double-curation): the `afterTurn` event → SweepService, once.
+ */
+export function isCuratorTrigger(trigger) {
+    return trigger.trigger.type === "event" && trigger.trigger.on === "afterTurn";
+}
+/**
+ * Resolve a project's post-turn CURATOR trigger from its `triggers` map (T5) — the
+ * canonical {@link CURATE_TRIGGER_NAME} if it IS a curator, else the first structural
+ * curator ({@link isCuratorTrigger}) declared. `null` when the project declares none
+ * (the IMPLICIT built-in default — an un-customised project sweeps exactly as the
+ * shipped sweeper). Pure, so both `SweepService` (enabled gate + prompt extension) and
+ * `HerdctlService` (sweeper model override) resolve the ONE curator the same way.
+ */
+export function curatorTriggerOf(triggers) {
+    if (!triggers)
+        return null;
+    const named = triggers[CURATE_TRIGGER_NAME];
+    if (named && isCuratorTrigger(named))
+        return named;
+    for (const t of Object.values(triggers))
+        if (isCuratorTrigger(t))
+            return t;
+    return null;
+}
+/**
+ * Project a trigger's {@link TriggerRun} onto the exact herdctl agent tool-config
+ * fields (snake_case), so an event/webhook trigger's OWN `trigger-<slug>-<name>`
+ * agent enforces the capability BY CONSTRUCTION. Always sets `allowed_tools` +
+ * `max_turns` so a trigger agent never silently inherits the keeper's broad default
+ * toolset; a tool-less trigger yields `allowed_tools: []` (the CLI runtime then
+ * denies every tool). The ONE place run→agent-config translation lives. (The exact
+ * analogue of `hookToAgentToolConfig`.)
+ */
+export function triggerToAgentToolConfig(run) {
+    const out = {
+        allowed_tools: run.tools ?? [],
+        max_turns: run.maxTurns ?? TRIGGER_DEFAULT_MAX_TURNS,
+    };
+    if (run.permissionMode)
+        out.permission_mode = run.permissionMode;
+    if (run.model)
+        out.model = run.model;
+    return out;
+}
+/**
+ * Project ONE schedule-type trigger onto the herdctl `ScheduleSchema` fields the
+ * cron engine reads (`type` `cron`|`interval`, the timer field, `resume_session`,
+ * `enabled`), for forwarding into the keeper agent's `schedules` block. The
+ * Paddock-only prompt (inline/`promptFile`) is resolved at fire time by the trigger
+ * handler, so herdctl only ever sees a plain `prompt` (or none) — kept pure. The
+ * `resume_session` flag is derived from `run.session` so herdctl's own new-vs-accrete
+ * stays in agreement with Paddock's (the handler still owns the OWNED-session sidecar).
+ */
+export function scheduleTriggerToHerdctl(when, run, enabled) {
+    const isCron = when.cron !== undefined;
+    const out = { type: isCron ? "cron" : "interval" };
+    if (isCron)
+        out.cron = when.cron;
+    else
+        out.interval = when.interval;
+    // Forward the inline prompt only when a promptFile isn't driving the trigger (the
+    // handler reads the file fresh at fire time and supplies the resolved text).
+    if (typeof run.prompt === "string" && run.promptFile === undefined)
+        out.prompt = run.prompt;
+    out.resume_session = run.session === "resume";
+    // Forward the Paddock-level enabled flag so herdctl's engine doesn't even fire a
+    // disabled schedule trigger (the handler double-checks too — belt and braces).
+    out.enabled = enabled;
+    return out;
+}
+/**
+ * Build the `schedules` block to forward into the keeper agent config from a
+ * project's SCHEDULE-type triggers, or `undefined` when it declares none. Non-schedule
+ * triggers (event/webhook) are skipped — they don't arm the cron engine. Keyed by
+ * trigger name (the same key the fire handler resolves back to a trigger).
+ */
+export function triggersToHerdctlSchedules(map) {
+    if (!map)
+        return undefined;
+    const out = {};
+    for (const [name, t] of Object.entries(map)) {
+        if (t.trigger.type !== "schedule")
+            continue;
+        out[name] = scheduleTriggerToHerdctl(t.trigger, t.run, t.enabled === true);
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+/**
+ * Project a persisted trigger ({@link TriggerDto} fields) onto the web-facing
+ * {@link ChatTriggerInfo}, resolving the SAME capability defaults
+ * {@link triggerToAgentToolConfig} uses so the banner mirrors the enforced grant
+ * exactly: an absent/empty allow-list surfaces as a tool-less `[]`, and an unset
+ * `maxTurns` surfaces the {@link TRIGGER_DEFAULT_MAX_TURNS} bound herdctl applies.
+ * The WHEN fields are read off the discriminated `trigger` so the banner can state
+ * the trigger type and the exact firing condition.
+ */
+export function toChatTriggerInfo(dto) {
+    const when = dto.trigger;
+    const run = dto.run;
+    const info = {
+        name: dto.name,
+        type: when.type,
+        agentName: dto.agentName,
+        enabled: dto.enabled === true,
+        allowedTools: run.tools ?? [],
+        maxTurns: run.maxTurns ?? TRIGGER_DEFAULT_MAX_TURNS,
+    };
+    if (when.type === "event")
+        info.event = when.on;
+    else if (when.type === "schedule") {
+        if (when.cron !== undefined)
+            info.cron = when.cron;
+        if (when.interval !== undefined)
+            info.interval = when.interval;
+    }
+    else if (when.type === "webhook")
+        info.path = when.path;
+    if (run.permissionMode)
+        info.permissionMode = run.permissionMode;
+    if (run.model)
+        info.model = run.model;
+    return info;
+}
+/**
+ * Resolve a `promptFile` to an absolute path under the project's `.paddock/triggers/`
+ * dir, or `null` if it escapes that dir, is absolute, or isn't a `.md` file. The name
+ * is treated as relative to the triggers dir (so a bare `"daily.md"` resolves to
+ * `<workingDir>/.paddock/triggers/daily.md`). Byte-for-byte the hook/schedule twin's guard.
+ */
+export function triggerPromptFileAbsPath(workingDir, promptFile) {
+    if (typeof promptFile !== "string" || promptFile.trim() === "")
+        return null;
+    const rel = promptFile.trim();
+    if (path.isAbsolute(rel))
+        return null;
+    const base = path.resolve(workingDir, TRIGGER_PROMPT_DIR);
+    const target = path.resolve(base, rel);
+    const within = target === base || target.startsWith(base + path.sep);
+    if (!within)
+        return null;
+    if (!target.toLowerCase().endsWith(".md"))
+        return null;
+    return target;
+}

package/packages/server/dist/trigger-runtime.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Per-trigger RUNTIME state builder (Epic T follow-up / #327) — the live "last-run /
+ * next-run / status" view the Triggers tab renders alongside each trigger's config.
+ *
+ * When Epic T (#305 / T4) folded the Settings→Schedules section into the unified
+ * Triggers tab, two capabilities were dropped because {@link TriggerDto} carries
+ * trigger *config* only, not herdctl *runtime* state: the old section could show a
+ * schedule's last/next run + status, and could fire it on demand. This module restores
+ * the STATUS half — it JOINS the config DTOs with two herdctl runtime sources:
+ *
+ *   - **`ScheduleInfo`** (the cron scheduler's live state, keyed by trigger name — the
+ *     same key the forwarded `schedules` block uses): `nextRunAt` (the only source of a
+ *     future fire time), `lastRunAt`, `status` (idle/running/disabled), and `lastError`.
+ *     Meaningful for SCHEDULE-type triggers only.
+ *   - **job records** (`JobMetadata`, per the E3/#268 run-history pattern): the trigger's
+ *     most-recent RUN — its session id, terminal status, exit reason, timing, and the
+ *     agent's one-line summary. Attributable ONLY for a trigger that runs on its OWN
+ *     scoped `trigger-<slug>-<name>` agent ({@link triggerRunsOnOwnAgent}): every event
+ *     trigger, and a schedule trigger with a `run.tools` allow-list (T2). An UNSCOPED
+ *     schedule trigger runs as the shared keeper, whose job records can't be attributed
+ *     back to one trigger — so its last-run falls back to `ScheduleInfo.lastRunAt`.
+ *
+ * The build step is deliberately PURE (no I/O): the route resolves the DTOs, the flat
+ * job list ({@link HerdctlService.listRunsForAgents}) and the schedule state
+ * ({@link HerdctlService.listAgentSchedules}), then hands them here so the join stays
+ * unit-testable — the same split {@link import("./runs.js").buildProjectRuns} uses.
+ */
+import type { JobMetadata } from "@herdctl/core";
+import { type TriggerDto } from "./trigger-config.js";
+/**
+ * The slice of herdctl's `ScheduleInfo` this builder consumes — a local structural
+ * type (mirrors the one in routes.ts / ws.ts) so the module stays off
+ * `@herdctl/core`'s import surface. Keyed by the trigger's name.
+ */
+export interface ScheduleRuntimeInfo {
+    status?: "idle" | "running" | "disabled";
+    lastRunAt?: string | null;
+    nextRunAt?: string | null;
+    lastError?: string | null;
+}
+/** The trigger's most-recent RUN, projected from a herdctl job record (or a schedule fire). */
+export interface TriggerLastRun {
+    /** herdctl job id, or null when the last-run is only known from schedule state. */
+    jobId: string | null;
+    /** The chat the run belongs to (link target), or null. */
+    sessionId: string | null;
+    /** Terminal/live status: completed | failed | cancelled | running | pending. */
+    status: string;
+    /** Why it exited (success | error | max_turns | timeout | cancelled), if recorded. */
+    exitReason: string | null;
+    /** ISO timestamp the run started. */
+    startedAt: string;
+    /** ISO timestamp the run finished, or null while running / unrecorded. */
+    finishedAt: string | null;
+    /** Wall-clock seconds, or null while running / unrecorded. */
+    durationSeconds: number | null;
+    /** The agent's own one-line summary of the run, when it wrote one. */
+    summary: string | null;
+}
+/** One trigger's live runtime state — the "status" half the Triggers tab renders. */
+export interface TriggerRuntime {
+    /** The trigger's name (its project.yaml map key). */
+    name: string;
+    /** WHEN discriminant, echoed so the client styles per type without re-parsing. */
+    type: "schedule" | "event" | "webhook";
+    /** True when a run is in flight (a live job, or the cron scheduler reports running). */
+    running: boolean;
+    /** ISO timestamp of the next scheduled fire (SCHEDULE triggers only), else null. */
+    nextRunAt: string | null;
+    /**
+     * The cron scheduler's status for a SCHEDULE trigger (idle/running/disabled), else
+     * null. Falls back to disabled/idle from the config `enabled` when herdctl hasn't
+     * armed it yet (or the keeper isn't running).
+     */
+    scheduleStatus: string | null;
+    /** The last fire's error message (SCHEDULE triggers), or null. */
+    lastError: string | null;
+    /** The most-recent run, or null when the trigger has never fired. */
+    lastRun: TriggerLastRun | null;
+}
+/**
+ * Join trigger config DTOs with herdctl runtime state into the per-trigger status view.
+ *
+ * @param triggers  The project's trigger DTOs (config only).
+ * @param runs      Job records for the project's keeper + trigger agents, most-recent
+ *                  first (as {@link HerdctlService.listRunsForAgents} returns). Grouped
+ *                  by `agent` here; a scoped trigger's newest own-agent job is its run.
+ * @param schedules The cron scheduler's live `ScheduleInfo` for the keeper's forwarded
+ *                  schedules (keyed by trigger name).
+ * @param slug      The project slug — to resolve each trigger's scoped agent name.
+ */
+export declare function buildTriggerRuntime(triggers: TriggerDto[], runs: JobMetadata[], schedules: Array<ScheduleRuntimeInfo & {
+    name: string;
+}>, slug: string): TriggerRuntime[];

package/packages/server/dist/trigger-runtime.js

@@ -0,0 +1,82 @@
+import { triggerAgentName } from "./herdctl.js";
+import { triggerRunsOnOwnAgent } from "./trigger-config.js";
+/** Project a job record onto the {@link TriggerLastRun} shape. */
+function lastRunFromJob(job) {
+    return {
+        jobId: job.id,
+        sessionId: job.session_id ?? null,
+        status: job.status,
+        exitReason: job.exit_reason ?? null,
+        startedAt: job.started_at,
+        finishedAt: job.finished_at ?? null,
+        durationSeconds: job.duration_seconds ?? null,
+        summary: job.summary ?? null,
+    };
+}
+/**
+ * Synthesize a minimal {@link TriggerLastRun} from the cron scheduler's `lastRunAt`
+ * for an UNSCOPED schedule trigger (no attributable job record). herdctl tracks only a
+ * timestamp + a `lastError`, so status is inferred: `failed` when the last fire erred,
+ * else `completed` (a still-running fire is surfaced via {@link TriggerRuntime.running}
+ * / `scheduleStatus`, not here).
+ */
+function lastRunFromSchedule(info) {
+    if (!info.lastRunAt)
+        return null;
+    return {
+        jobId: null,
+        sessionId: null,
+        status: info.lastError ? "failed" : "completed",
+        exitReason: info.lastError ? "error" : null,
+        startedAt: info.lastRunAt,
+        finishedAt: info.lastRunAt,
+        durationSeconds: null,
+        summary: null,
+    };
+}
+/**
+ * Join trigger config DTOs with herdctl runtime state into the per-trigger status view.
+ *
+ * @param triggers  The project's trigger DTOs (config only).
+ * @param runs      Job records for the project's keeper + trigger agents, most-recent
+ *                  first (as {@link HerdctlService.listRunsForAgents} returns). Grouped
+ *                  by `agent` here; a scoped trigger's newest own-agent job is its run.
+ * @param schedules The cron scheduler's live `ScheduleInfo` for the keeper's forwarded
+ *                  schedules (keyed by trigger name).
+ * @param slug      The project slug — to resolve each trigger's scoped agent name.
+ */
+export function buildTriggerRuntime(triggers, runs, schedules, slug) {
+    // Newest job per agent — `runs` is already most-recent-first, so the FIRST match wins.
+    const newestByAgent = new Map();
+    for (const job of runs) {
+        if (!newestByAgent.has(job.agent))
+            newestByAgent.set(job.agent, job);
+    }
+    const scheduleByName = new Map(schedules.map((s) => [s.name, s]));
+    return triggers.map((dto) => {
+        const type = dto.trigger.type;
+        const isSchedule = type === "schedule";
+        const info = isSchedule ? scheduleByName.get(dto.name) : undefined;
+        // A scoped trigger (every event; a schedule with a `run.tools` allow-list) writes
+        // job records under its OWN agent — attribute its newest one. An unscoped schedule
+        // runs as the shared keeper (no per-trigger attribution) — fall back to the cron
+        // scheduler's timestamp.
+        const job = triggerRunsOnOwnAgent(dto)
+            ? newestByAgent.get(triggerAgentName(slug, dto.name))
+            : undefined;
+        const lastRun = job ? lastRunFromJob(job) : info ? lastRunFromSchedule(info) : null;
+        const running = job?.status === "running" || info?.status === "running" || false;
+        const scheduleStatus = isSchedule
+            ? info?.status ?? (dto.enabled === false ? "disabled" : "idle")
+            : null;
+        return {
+            name: dto.name,
+            type,
+            running,
+            nextRunAt: isSchedule ? info?.nextRunAt ?? null : null,
+            scheduleStatus,
+            lastError: isSchedule ? info?.lastError ?? null : null,
+            lastRun,
+        };
+    });
+}

package/packages/server/dist/trigger-session.d.ts

@@ -0,0 +1,34 @@
+export declare class TriggerSessionStore {
+    private readonly stateFile;
+    /** In-memory map of `<slug>\0<triggerName>` -> owned sessionId. */
+    private state;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read (the
+     * RunProvenanceStore fix): caching only the resolved `state` would let several
+     * fires that begin before the first `fs.readFile` resolves each build their own
+     * map and race on the assignment — a lost update.
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    private static key;
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /** The session id this trigger owns, or undefined if it hasn't fired yet. Non-throwing. */
+    get(slug: string, triggerName: string): Promise<string | undefined>;
+    /**
+     * Record the session a trigger owns (its first-fire chat). Idempotent for the same
+     * id; an unsafe/blank id is ignored. Overwrites if called again (used only on a
+     * fresh first fire, or to re-point after a stale id was cleared).
+     */
+    set(slug: string, triggerName: string, sessionId: string): Promise<void>;
+    /**
+     * Forget a trigger's owned session — used when the recorded transcript has vanished
+     * (so the next fire re-creates one) or the trigger was removed. No-op if there was
+     * nothing recorded.
+     */
+    clear(slug: string, triggerName: string): Promise<void>;
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    private persist;
+}