@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/ws-protocol.js

@@ -0,0 +1,251 @@
+function num(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+/**
+ * Defensively extract per-turn usage + model from a raw SDK message. The SDK's
+ * `message` is typed `unknown` in core, and the CLI/SDK runtimes shape usage
+ * slightly differently, so every field access is guarded.
+ *
+ * - assistant message: `m.message.usage` (Anthropic usage block) + `m.message.model`.
+ * - result message: top-level `m.usage` (same field names). Flagged `fromResult`
+ *   because that block is a cumulative per-turn total, not a snapshot (#398).
+ *
+ * Returns `{ usage: null, model: null, fromResult: false }` when neither is present.
+ */
+export function extractUsage(m) {
+    const raw = m;
+    const fromResult = raw.type === "result";
+    // Locate the usage block + model from whichever shape this message carries.
+    let usageBlock;
+    let model = null;
+    const inner = raw.message && typeof raw.message === "object"
+        ? raw.message
+        : undefined;
+    if (inner) {
+        if (inner.usage !== undefined)
+            usageBlock = inner.usage;
+        if (typeof inner.model === "string")
+            model = inner.model;
+    }
+    // Result messages (and some shapes) carry usage at the top level.
+    if (usageBlock === undefined && raw.usage !== undefined)
+        usageBlock = raw.usage;
+    if (usageBlock === undefined || usageBlock === null || typeof usageBlock !== "object") {
+        return { usage: null, model, fromResult };
+    }
+    const u = usageBlock;
+    const usage = {
+        inputTokens: num(u.input_tokens),
+        outputTokens: num(u.output_tokens),
+        cacheCreationTokens: num(u.cache_creation_input_tokens),
+        cacheReadTokens: num(u.cache_read_input_tokens),
+    };
+    // A usage block of all-zeros (e.g. a stub) is not informative; treat as none.
+    const anyTokens = usage.inputTokens || usage.outputTokens || usage.cacheCreationTokens || usage.cacheReadTokens;
+    return { usage: anyTokens ? usage : null, model, fromResult };
+}
+/** The `<synthetic>` model marker CC stamps on placeholder assistant turns. */
+const SYNTHETIC_MODEL = "<synthetic>";
+/**
+ * Bare synthetic placeholders that carry no output worth surfacing — e.g. the
+ * "No response requested." turn CC injects after a `/compact` continuation. Only a
+ * synthetic message with *substantive* text is a genuine local-command result.
+ */
+const SYNTHETIC_PLACEHOLDERS = new Set(["No response requested."]);
+/**
+ * The rendered output of a client-local slash command (`/context`, `/usage`, …) to
+ * surface as an assistant note, or null when this SDK message isn't one (issue #158).
+ *
+ * The interactive TUI renders these locally; a non-interactive SDK session (Paddock's
+ * path) instead surfaces the output as EITHER a `type:"system"` / `local_command`
+ * entry (its `content` wraps the output in `<local-command-stdout>…`) or a
+ * `model:"<synthetic>"` assistant placeholder carrying the text. @herdctl/chat's
+ * translator drops both (synthetic messages are skipped; system entries aren't text),
+ * so the live command turn would otherwise read as a silent no-op. We recover the text
+ * and emit it as an assistant note (mirroring the `compact_boundary` special-case),
+ * consistent with the history-path recovery in `localcommand.ts`. Bare placeholders
+ * (e.g. `/compact`'s "No response requested.") yield null so they stay quiet. Paddock's
+ * own context ring + cost meter remain the primary usage view; this just stops the
+ * output vanishing.
+ */
+export function extractLocalCommandOutput(m) {
+    const raw = m;
+    // Disk/canonical form: a `system` / `local_command` entry wrapping the stdout.
+    if (raw.type === "system" && raw.subtype === "local_command") {
+        const content = typeof raw.content === "string" ? raw.content : "";
+        const inner = /<local-command-stdout>([\s\S]*)<\/local-command-stdout>/.exec(content)?.[1];
+        const text = (inner ?? "").trim();
+        return text.length > 0 ? text : null;
+    }
+    // Live/stream form: a synthetic placeholder assistant message carrying the text.
+    if (raw.type !== "assistant")
+        return null;
+    const inner = raw.message && typeof raw.message === "object"
+        ? raw.message
+        : undefined;
+    if (!inner || inner.model !== SYNTHETIC_MODEL)
+        return null;
+    let text = "";
+    if (typeof inner.content === "string")
+        text = inner.content;
+    else if (Array.isArray(inner.content)) {
+        for (const block of inner.content) {
+            const b = block;
+            if (b?.type === "text" && typeof b.text === "string")
+                text += b.text;
+        }
+    }
+    text = text.trim();
+    if (text.length === 0 || SYNTHETIC_PLACEHOLDERS.has(text))
+        return null;
+    return text;
+}
+/**
+ * The context snapshot a usage block implies: the tokens resident in the model's
+ * context window for this turn (fresh input + cache reads + cache creation).
+ */
+function contextTokensOf(u) {
+    return u.inputTokens + u.cacheReadTokens + u.cacheCreationTokens;
+}
+/**
+ * Merge two context-snapshot usage blocks, keeping whichever best reflects the
+ * context window (issue #165). Only assistant / partial-assistant blocks are ever
+ * passed here — the terminal `result` block is folded separately (see
+ * {@link foldTurnUsage}), because its usage is cumulative, not a snapshot (#398).
+ *
+ * Assistant usage grows monotonically through a turn (each round re-reads the
+ * cached prefix), so "last assistant" == "max assistant". We still keep the MAX
+ * `contextTokens` (input + cacheRead + cacheCreation) defensively: an odd
+ * cache-less block can never LOWER the snapshot. `outputTokens` keeps the max
+ * seen.
+ */
+export function pickTurnUsage(prev, next) {
+    if (!prev)
+        return next;
+    const chosen = contextTokensOf(next) >= contextTokensOf(prev) ? next : prev;
+    return {
+        ...chosen,
+        outputTokens: Math.max(prev.outputTokens, next.outputTokens),
+    };
+}
+/** A fresh, empty per-turn usage accumulator. */
+export function initTurnUsage() {
+    return { snapshot: null, cumulative: null, model: null };
+}
+/**
+ * Fold one raw SDK message into the running usage state. Mirrors exactly what the
+ * ws.ts stream loop does, so tests can drive it the same way. Assistant usage
+ * accumulates into the context snapshot; the terminal `result` block is stashed
+ * separately as the turn's cumulative total (#398).
+ */
+export function foldTurnUsage(state, m) {
+    const ex = extractUsage(m);
+    if (ex.usage) {
+        if (ex.fromResult)
+            state.cumulative = ex.usage;
+        else
+            state.snapshot = pickTurnUsage(state.snapshot, ex.usage);
+    }
+    if (ex.model)
+        state.model = ex.model;
+    return state;
+}
+/**
+ * Resolve the final per-turn usage emitted on `chat:complete`. `contextTokens`
+ * always derives from the snapshot (the true window). The cumulative result block
+ * is used only to lift `outputTokens` to the turn's final total, and as a
+ * last-resort fallback for context if NO assistant usage was seen this turn (some
+ * runtimes emit usage only on the result — there cumulative == the single call).
+ */
+export function resolveTurnUsage(state) {
+    const base = state.snapshot ?? state.cumulative;
+    if (!base)
+        return null;
+    return {
+        ...base,
+        outputTokens: Math.max(base.outputTokens, state.cumulative?.outputTokens ?? 0),
+    };
+}
+export function isClientMessage(data) {
+    if (typeof data !== "object" || data === null)
+        return false;
+    const m = data;
+    if (m.type === "ping")
+        return true;
+    if (m.type === "chat:cancel") {
+        const p = m.payload;
+        return !!p && typeof p.jobId === "string";
+    }
+    if (m.type === "chat:send") {
+        const p = m.payload;
+        if (!p || typeof p.message !== "string")
+            return false;
+        const slug = p.projectSlug;
+        if (typeof slug !== "string")
+            return false;
+        if (p.preloadContext !== undefined && typeof p.preloadContext !== "boolean")
+            return false;
+        if (p.model !== undefined && typeof p.model !== "string")
+            return false;
+        if (p.attachments !== undefined) {
+            if (!Array.isArray(p.attachments))
+                return false;
+            for (const a of p.attachments) {
+                if (!a || typeof a !== "object")
+                    return false;
+                const ao = a;
+                if (typeof ao.id !== "string" || typeof ao.filename !== "string")
+                    return false;
+                if (ao.kind !== undefined && typeof ao.kind !== "string")
+                    return false;
+            }
+        }
+        return p.sessionId === undefined || p.sessionId === null || typeof p.sessionId === "string";
+    }
+    if (m.type === "chat:command") {
+        const p = m.payload;
+        if (!p || typeof p.command !== "string" || p.command.length === 0)
+            return false;
+        const slug = p.projectSlug;
+        if (typeof slug !== "string")
+            return false;
+        return p.sessionId === undefined || p.sessionId === null || typeof p.sessionId === "string";
+    }
+    if (m.type === "chat:subscribe") {
+        const p = m.payload;
+        if (!p || typeof p.sessionId !== "string" || p.sessionId.length === 0)
+            return false;
+        if (p.wantReplay !== undefined && typeof p.wantReplay !== "boolean")
+            return false;
+        if (p.lastSeq !== undefined && typeof p.lastSeq !== "number")
+            return false;
+        return true;
+    }
+    if (m.type === "chat:continue") {
+        const p = m.payload;
+        if (!p || typeof p.sessionId !== "string" || p.sessionId.length === 0)
+            return false;
+        const slug = p.projectSlug;
+        return typeof slug === "string";
+    }
+    if (m.type === "chat:set_queue") {
+        // NOTE: this case was missing until #245 — every chat:set_queue was rejected
+        // as "Unknown message", so the server-side queue (#197) never persisted a
+        // thing. That's the deeper reason a queued message could strand: the backstop
+        // was never armed. Validate leniently (all payload fields optional bar slug).
+        const p = m.payload;
+        if (!p)
+            return false;
+        const slug = p.projectSlug;
+        if (typeof slug !== "string")
+            return false;
+        if (p.sessionId !== undefined && p.sessionId !== null && typeof p.sessionId !== "string")
+            return false;
+        if (p.text !== undefined && p.text !== null && typeof p.text !== "string")
+            return false;
+        if (p.ts !== undefined && p.ts !== null && typeof p.ts !== "number")
+            return false;
+        return true;
+    }
+    return false;
+}

package/packages/server/dist/ws-self-mcp.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Self-management MCP server-def assembly (extracted from ws.ts in #403; the ops
+ * construction moved out to management-ops.ts in #312 M1).
+ *
+ * What remains here is exactly the MCP-TRANSPORT concern: take a caller's built
+ * {@link ManagementOps} and turn them into an {@link InjectedMcpServerDef}. The
+ * operations themselves — and the policy that guards them — now live in
+ * management-ops.ts, so a non-MCP caller (the `/mcp` transport now, REST parity
+ * in #465) reaches the same ops without going through this module.
+ *
+ * `forkKickoffPrompt` is re-exported for its existing importers (ws.ts re-exports
+ * it in turn, and its unit test resolves it via ws.js).
+ */
+import type { InjectedMcpServerDef } from "@herdctl/core";
+import type { ChatHandlerContext } from "./ws-context.js";
+import type { RunProvenance } from "./run-provenance.js";
+import { type ManagementOps } from "./management-ops.js";
+import { type ManagementPrincipal } from "./management-policy.js";
+export { forkKickoffPrompt } from "./management-ops.js";
+/**
+ * Assemble an MCP server def from already-built, already-policed ops. This is
+ * the seam the `/mcp` transport uses: authenticate → build ops for the principal
+ * → hand them here.
+ */
+export declare function selfMcpServerDefForOps(ops: ManagementOps, principal: ManagementPrincipal): InjectedMcpServerDef;
+/**
+ * Build the self-management MCP server def (issue #214) bound to one turn's
+ * context — the IN-PROCESS keeper path.
+ *
+ * Runs under {@link INTERNAL_PRINCIPAL}: a keeper is bounded by depth
+ * (`maxSpawnDepth`, #278), not by auth+scope, so policy short-circuits to allow
+ * and this path behaves exactly as it did before #312.
+ *
+ * `parentProvenance` is the provenance of the chat these tools run IN — so any
+ * child they spawn is `childOf(parentProvenance)` (origin `spawned`, depth+1).
+ */
+export declare function buildSelfMcpServerDef(ctx: ChatHandlerContext, params: {
+    currentProjectSlug: string;
+    currentSessionId: () => string | null;
+    parentProvenance: RunProvenance;
+    includeWrite: boolean;
+    /**
+     * Whether to additionally append the Epic T / T3 unified trigger-management
+     * tools. Resolved per-project by the caller from the REUSED hooks-MCP gate.
+     */
+    includeTriggers: boolean;
+    /**
+     * Whether to expose `create_project` (#467) — its own instance-level gate,
+     * separate from the other write tools.
+     */
+    includeProjects: boolean;
+}): InjectedMcpServerDef;

package/packages/server/dist/ws-self-mcp.js

@@ -0,0 +1,28 @@
+import { selfMcpServerDef } from "./self-mcp.js";
+import { buildManagementOps, enforceManagementPolicy, managementToolFilter, } from "./management-ops.js";
+import { INTERNAL_PRINCIPAL } from "./management-policy.js";
+export { forkKickoffPrompt } from "./management-ops.js";
+/**
+ * Assemble an MCP server def from already-built, already-policed ops. This is
+ * the seam the `/mcp` transport uses: authenticate → build ops for the principal
+ * → hand them here.
+ */
+export function selfMcpServerDefForOps(ops, principal) {
+    return selfMcpServerDef(ops.read, ops.write, { toolFilter: managementToolFilter(principal) });
+}
+/**
+ * Build the self-management MCP server def (issue #214) bound to one turn's
+ * context — the IN-PROCESS keeper path.
+ *
+ * Runs under {@link INTERNAL_PRINCIPAL}: a keeper is bounded by depth
+ * (`maxSpawnDepth`, #278), not by auth+scope, so policy short-circuits to allow
+ * and this path behaves exactly as it did before #312.
+ *
+ * `parentProvenance` is the provenance of the chat these tools run IN — so any
+ * child they spawn is `childOf(parentProvenance)` (origin `spawned`, depth+1).
+ */
+export function buildSelfMcpServerDef(ctx, params) {
+    const ops = buildManagementOps(ctx, params);
+    const policed = enforceManagementPolicy(ops, INTERNAL_PRINCIPAL);
+    return selfMcpServerDefForOps(policed, INTERNAL_PRINCIPAL);
+}

package/packages/server/dist/ws-triggers.d.ts

@@ -0,0 +1,29 @@
+import { type TriggerDto, type TriggerEvent } from "./trigger-config.js";
+import type { ChatHandlerDeps, StartAgentTurn } from "./ws-context.js";
+/**
+ * The context a fired lifecycle event carries into an EVENT trigger's prompt (Epic T /
+ * T1). v1 (`onArchive`) supplies the archived chat's session id so the trigger knows
+ * what to act on.
+ */
+export interface TriggerEventContext {
+    /** The session id of the chat whose lifecycle event fired the trigger. */
+    sessionId: string;
+}
+/** The shared trigger-firing surface `makeChatHandler` consumes + returns. */
+export interface TriggerCluster {
+    /** Post-turn curation signal (T5): emit `afterTurn` so the sweeper runs once. */
+    emitAfterTurn(slug: string, sessionId: string | null): void;
+    /** Prepend the OVERVIEW+CHANGELOG preload block for a new chat (issues #1/#188). */
+    composePreloadedPrompt(projectSlug: string, baseMessage: string): Promise<string>;
+    /** Fire a named trigger on demand (Run-now / run_trigger); resolves its chat id or null. */
+    fireTrigger(slug: string, triggerName: string): Promise<string | null>;
+    /** Run one fire of a resolved trigger record as a first-class chat on the hub. */
+    fireTriggerForProject(project: Awaited<ReturnType<ChatHandlerDeps["projects"]["get"]>>, trigger: TriggerDto, ctx?: TriggerEventContext): Promise<string | null>;
+    /** Fire every enabled EVENT trigger matching `event` for a project (after-commit). */
+    dispatchEventTriggers(slug: string, event: TriggerEvent, ctx: TriggerEventContext): Promise<void>;
+}
+/**
+ * Build the trigger-firing cluster bound to the handler's deps + the shared
+ * `startAgentTurn` engine, and wire its schedule/event listeners.
+ */
+export declare function makeTriggerCluster(deps: ChatHandlerDeps, startAgentTurn: StartAgentTurn): TriggerCluster;

package/packages/server/dist/ws-triggers.js

@@ -0,0 +1,261 @@
+/**
+ * Trigger / schedule / event firing cluster, extracted from ws.ts (#403).
+ *
+ * `makeTriggerCluster(deps, startAgentTurn)` returns the shared firing surface and
+ * wires the herdctl schedule handler + the onArchive / afterTurn event listeners.
+ * Every trigger type funnels through ONE `startAgentTurn` call (the shared engine,
+ * passed in) so a cron / event / manual "Run now" fire is indistinguishable.
+ *
+ * Also holds two helpers historically co-located with the firing code: the
+ * post-turn `emitAfterTurn` curation signal (T5 sweeper) and `composePreloadedPrompt`
+ * (the OVERVIEW+CHANGELOG new-chat preload, shared by the human path + self-MCP).
+ */
+import { promises as fs } from "node:fs";
+import { isKnownDriveMode } from "./models.js";
+import { keeperAgentName, keeperSlugFromAgent, triggerAgentName, } from "./herdctl.js";
+import { resolveMaxSpawnDepth } from "./spawn-capability.js";
+import { wrapPreload, composePreloadContext } from "./preload.js";
+import { triggerPromptFileAbsPath, triggerRunsOnOwnAgent, isCuratorTrigger, } from "./trigger-config.js";
+/**
+ * Build the trigger-firing cluster bound to the handler's deps + the shared
+ * `startAgentTurn` engine, and wire its schedule/event listeners.
+ */
+export function makeTriggerCluster(deps, startAgentTurn) {
+    /** Resolve a project's effective keeper drive mode (override else instance default). */
+    function resolveDriveMode(project) {
+        return project.driveMode && isKnownDriveMode(project.driveMode)
+            ? project.driveMode
+            : deps.cfg.driveMode;
+    }
+    // Drive scheduler-fired chats onto the hub (issue #265 / DD-1, DD-2). herdctl's
+    // cron engine fires a project keeper's declared schedule and routes it HERE
+    // (setScheduleTriggerHandler) instead of running it headless.
+    deps.herdctl.onScheduleTrigger(async (info) => {
+        const slug = keeperSlugFromAgent(info.agent.name);
+        // Only keeper agents carry Paddock schedules; a non-keeper trigger (there are
+        // none today) has nowhere sensible to route, so ignore it rather than guess.
+        // `null` means "not a keeper"; `""` is the ROOT workspace's own key, so this
+        // must not be a falsy check.
+        if (slug === null)
+            return;
+        const project = await deps.projects.get(slug).catch(() => null);
+        if (!project)
+            return;
+        // Every armed keeper schedule belongs to a SCHEDULE-type trigger (forwarded into
+        // the keeper `schedules` block under its trigger name). Resolve + fire it via the
+        // single trigger fire path.
+        const trig = project.triggers?.[info.scheduleName];
+        if (trig && trig.trigger.type === "schedule" && trig.enabled === true) {
+            await fireTriggerForProject(project, {
+                name: info.scheduleName,
+                agentName: triggerAgentName(slug, info.scheduleName),
+                ...trig,
+            });
+        }
+        // A fired keeper schedule with no matching enabled SCHEDULE trigger is ignored:
+        // triggers are the only thing forwarded into the keeper's `schedules` block.
+    });
+    // --- unified triggers (Epic T / T1) ------------------------------------
+    /**
+     * Resolve the prompt a fired trigger should run. A trigger's `promptFile`
+     * (Paddock-only, `.paddock/triggers/*.md`, git-tracked + keeper-editable) is read
+     * FRESH here at fire time — so an edit takes effect on the very next fire with no
+     * agent re-register — and falls back to the inline `run.prompt` when there's no file
+     * or it can't be read. For an EVENT trigger, a short machine preamble naming the
+     * event + archived chat is prepended (so the trigger knows WHAT to act on); a
+     * schedule trigger gets no preamble. Mirrors {@link resolveSchedulePrompt} /
+     * {@link resolveHookPrompt}.
+     */
+    async function resolveTriggerPrompt(project, trigger, ctx) {
+        let body = typeof trigger.run.prompt === "string" ? trigger.run.prompt : "";
+        if (trigger.run.promptFile) {
+            const abs = triggerPromptFileAbsPath(project.workingDir, trigger.run.promptFile);
+            if (abs) {
+                const content = await fs.readFile(abs, "utf8").catch(() => null);
+                if (content !== null)
+                    body = content;
+            }
+        }
+        if (trigger.trigger.type === "event" && ctx) {
+            const preamble = `A \`${trigger.trigger.on}\` event trigger fired for project \`${project.slug}\`: ` +
+                `chat \`${ctx.sessionId}\` was just archived.\n\n`;
+            return preamble + body;
+        }
+        return body;
+    }
+    /**
+     * Run one fire of a trigger as a first-class chat on the hub — the ONE fire path for
+     * every trigger type (Epic T), replacing the separate schedule + hook fire paths with
+     * a single `startAgentTurn` call. Whether the fired turn runs on the trigger's OWN
+     * scoped `trigger-<slug>-<name>` agent (tool config = `run.tools`) or on the keeper is
+     * decided by {@link triggerRunsOnOwnAgent}: an EVENT trigger always runs scoped; a
+     * SCHEDULE trigger runs scoped ONLY when it declares a non-empty `run.tools` allow-list
+     * (T2 — #307), otherwise it runs as the keeper with the project-agent default toolset
+     * (pre-T2 behaviour, unchanged). `run.maxSpawnDepth` gates this fire's self-MCP spawn
+     * capability regardless of which agent runs it.
+     *
+     * `run.session` drives new-vs-accrete: `"new"` → a FRESH chat every fire
+     * (`resume: null`); `"resume"` → resume the trigger's ONE owned session (recorded on
+     * first fire in the {@link TriggerSessionStore}, rebound after a restart) so a
+     * "manager" accretes a single transcript. A stale owned id (its transcript deleted)
+     * is forgotten so the next fire re-creates one. FIRE-AND-FORGET: a rejection (the
+     * turn never produced a session id — its own failure frame already emitted) is
+     * swallowed so a transient failure never wedges the trigger. Resolves the
+     * created/resumed session id, or `null`.
+     */
+    async function fireTriggerForProject(project, trigger, ctx) {
+        const slug = project.slug;
+        const isSchedule = trigger.trigger.type === "schedule";
+        // T2: a scoped trigger (every event; a schedule with a `run.tools` allow-list) runs
+        // on its OWN `trigger-<slug>-<name>` agent so herdctl enforces its capability; an
+        // unscoped schedule runs as the keeper (project-agent default toolset, unchanged).
+        const onOwnAgent = triggerRunsOnOwnAgent(trigger);
+        const agentName = onOwnAgent ? triggerAgentName(slug, trigger.name) : keeperAgentName(slug);
+        const prompt = await resolveTriggerPrompt(project, trigger, ctx);
+        // run.session: "resume" accretes into an owned session; "new" starts fresh.
+        let resume = null;
+        if (trigger.run.session === "resume" && deps.triggerSessions) {
+            const owned = await deps.triggerSessions.get(slug, trigger.name).catch(() => undefined);
+            if (owned && (await deps.herdctl.sessionExists(project, owned).catch(() => false))) {
+                resume = owned;
+            }
+            else if (owned) {
+                await deps.triggerSessions.clear(slug, trigger.name).catch(() => undefined);
+            }
+        }
+        try {
+            const sessionId = await startAgentTurn({
+                projectSlug: slug,
+                agentName,
+                workingDir: project.workingDir,
+                resume,
+                prompt,
+                driveMode: resolveDriveMode(project),
+                fallbackModel: trigger.run.model ?? project.model,
+                // Provenance (A1/#261): a schedule fire is a root `scheduled` trigger; an event
+                // trigger reuses the `hook` origin (its E1 badge surface) — both depth 0.
+                origin: isSchedule ? "scheduled" : "hook",
+                depth: 0,
+                // A per-trigger `run.maxSpawnDepth` (design §2.3, T2) gates this fire's self-MCP
+                // spawn capability; it wins over the project override, which wins over the
+                // instance default (reuses B1's resolver).
+                maxSpawnDepth: resolveMaxSpawnDepth(trigger.run.maxSpawnDepth ?? project.maxSpawnDepth, deps.cfg.maxSpawnDepth),
+                // Attribute the injected kickoff turn to the trigger that fired it (#290).
+                sender: {
+                    kind: isSchedule ? "schedule" : "hook",
+                    name: trigger.name,
+                    project: slug,
+                },
+            });
+            // First fire of an accreting trigger: remember the chat it created so the next
+            // fire resumes THIS transcript (a resume already had an id).
+            if (trigger.run.session === "resume" && !resume && deps.triggerSessions) {
+                await deps.triggerSessions.set(slug, trigger.name, sessionId).catch(() => undefined);
+            }
+            return sessionId;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Resolve a project's ENABLED event triggers for `event` and fire each (after-commit,
+     * non-blocking — after-commit, non-blocking). Concurrent +
+     * independent; one trigger's failure never affects another. No-op when the trigger
+     * system isn't wired ({@link makeChatHandler} dep `triggers` absent) or the project
+     * has no matching enabled event trigger.
+     */
+    async function dispatchEventTriggers(slug, event, ctx) {
+        if (!deps.triggers)
+            return;
+        const project = await deps.projects.get(slug).catch(() => null);
+        if (!project)
+            return;
+        const matching = await deps.triggers.enabledForEvent(slug, event).catch(() => []);
+        await Promise.all(matching.map((trigger) => fireTriggerForProject(project, trigger, ctx)));
+    }
+    // Dispatch enabled EVENT triggers on the SAME lifecycle events hooks fire on — the
+    // event-bus supports multiple listeners, so this rides alongside the hook dispatcher
+    // (they read disjoint config blocks). onArchive is the wired event; afterTurn is
+    // reserved for the sweeper fold-in (T5) and not emitted yet.
+    deps.events?.on("onArchive", (payload) => {
+        void dispatchEventTriggers(payload.slug, "onArchive", { sessionId: payload.sessionId });
+    });
+    /**
+     * Signal a completed turn's post-turn CURATION (Epic T / T5) — the sweeper, folded in
+     * as the default `curate-overview` (event/afterTurn) trigger. Emits the `afterTurn`
+     * lifecycle event so the curator dispatches EXACTLY ONCE per turn (its enabled gate +
+     * per-project prompt extension resolved inside SweepService). Fires for every
+     * workspace, the root included.
+     * Falls back to a direct `sweep.enqueue` when the event bus isn't wired (older
+     * callers / tests), so behaviour is identical with or without the bus. Called from
+     * every post-turn commit site (a human chat turn, a session-mode wake, and every
+     * server-initiated `startAgentTurn`) — the ONE place the sweeper is now triggered.
+     */
+    function emitAfterTurn(slug, sessionId) {
+        if (deps.events)
+            deps.events.emit("afterTurn", { slug, sessionId });
+        else
+            deps.sweep?.enqueue(slug);
+    }
+    // The folded-in sweeper (T5): `afterTurn` drives the default post-turn curator. Unlike
+    // `onArchive`, afterTurn is NOT fanned out to generic `trigger-<slug>-<name>` agents —
+    // the curator is tool-less and executed by SweepService (returns marked text, Paddock
+    // writes OVERVIEW.md/CHANGELOG.md). So this is the SOLE afterTurn consumer, which is
+    // what guarantees the sweeper runs exactly once per turn (no double-curation).
+    deps.events?.on("afterTurn", (payload) => {
+        deps.sweep?.enqueue(payload.slug);
+    });
+    /**
+     * Fire a TRIGGER now (Epic T / T1), reused by the "Run now" REST route + `run_trigger`
+     * self-MCP verb (#327) and shared with the cron path below. Resolves the live project +
+     * its trigger record and fires via {@link fireTriggerForProject} — through the SAME hub
+     * path a cron/event fire uses, so a manual run is indistinguishable from an automatic
+     * one. Fires ANY trigger type on demand (a schedule, an event trigger, or a reserved
+     * webhook trigger you want to smoke-test before its ingress lands) regardless of its
+     * `enabled` flag — a manual run is a deliberate act (mirrors the schedule DD-1 rule).
+     * Returns the started chat's session id, or `null` if the project/trigger is gone or
+     * the turn never produced a session.
+     */
+    async function fireTrigger(slug, triggerName) {
+        const project = await deps.projects.get(slug).catch(() => null);
+        if (!project)
+            return null;
+        const rec = project.triggers?.[triggerName];
+        if (!rec)
+            return null;
+        // The post-turn CURATOR (any `event`/`afterTurn` trigger — the folded-in sweeper, T5)
+        // is NOT fireable on the generic path: it registers no scoped `trigger-<slug>-<name>`
+        // agent and runs via SweepService on `afterTurn`. Refuse rather than firing a turn on
+        // a non-existent agent (defence-in-depth — the REST route + run_trigger MCP reject it
+        // up front with a clear message; this guards any other caller).
+        if (isCuratorTrigger(rec))
+            return null;
+        return fireTriggerForProject(project, { name: triggerName, agentName: triggerAgentName(slug, triggerName), ...rec });
+    }
+    /**
+     * Compose the OVERVIEW.md + CHANGELOG.md preload block onto `baseMessage` for
+     * a NEW chat (issues #1/#188), shared (C2 / #264) by the human New-Chat path
+     * and the self-MCP `create_chat` spawn path so both inject the SAME context.
+     * Injects only when the project has an OVERVIEW.md (the signal that a sweep
+     * has curated real state); when it fires it prepends BOTH the overview
+     * (current state) AND the CHANGELOG.md (cross-session history), matching the
+     * UI checkbox. Returns `baseMessage` unchanged when there's no overview yet.
+     */
+    async function composePreloadedPrompt(projectSlug, baseMessage) {
+        const overview = await deps.projects.readOverview(projectSlug).catch(() => "");
+        if (overview.trim().length === 0)
+            return baseMessage;
+        const changelog = await deps.projects.readChangelog(projectSlug).catch(() => "");
+        // Single-sourced wrapper (see preload.ts) so the chat-list can strip it back
+        // off for display (issue #62).
+        return wrapPreload(composePreloadContext(overview, changelog), baseMessage);
+    }
+    return {
+        emitAfterTurn,
+        composePreloadedPrompt,
+        fireTrigger,
+        fireTriggerForProject,
+        dispatchEventTriggers,
+    };
+}