@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/routes/triggers.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Trigger routes (Epic T "Unify Triggers" / T3) — the per-project UNIFIED trigger
+ * management surface the Triggers tab drives, the sole successor that collapses the
+ * retired hooks + schedules REST/verbs onto ONE `TriggerService` over
+ * `project.yaml`'s single `triggers` block. A trigger is WHEN (`trigger`, a
+ * discriminated union `schedule|event|webhook`) + WHAT (`run`, the shared agent-run
+ * definition) + `enabled`. Each route delegates to TriggerService, which persists to
+ * project.yaml FIRST (the source of truth, re-armed on restart) THEN arms it,
+ * warning-but-not-failing if the runtime arm hiccups.
+ *
+ * Verb collapse (GG-3): enable/disable is NOT a separate route — it's `set` (PUT)
+ * with the `enabled` field flipped; new triggers default disabled.
+ */
+import type { FastifyInstance } from "fastify";
+import type { RouteCtx } from "../route-context.js";
+/**
+ * The workspace-scoped trigger surface: registered once per workspace mount
+ * (root and per project) — see `workspace-mount.ts`. Paths are relative to the
+ * mount.
+ */
+export declare function registerTriggerWorkspaceRoutes(app: FastifyInstance, ctx: RouteCtx): void;

package/packages/server/dist/routes/triggers.js

@@ -0,0 +1,324 @@
+import { keeperAgentName } from "../herdctl.js";
+import { GRANTABLE_TOOLS } from "../hook-config.js";
+import { buildTriggerRuntime } from "../trigger-runtime.js";
+import { TRIGGER_EVENTS, TRIGGER_TYPES, isValidTriggerName, isCuratorTrigger, sanitizeTrigger, } from "../trigger-config.js";
+import { sendProjectError } from "../route-errors.js";
+/**
+ * The workspace-scoped trigger surface: registered once per workspace mount
+ * (root and per project) — see `workspace-mount.ts`. Paths are relative to the
+ * mount.
+ */
+export function registerTriggerWorkspaceRoutes(app, ctx) {
+    const { projects, herdctl, triggers, fireTrigger } = ctx;
+    const triggersGuard = (reply) => {
+        if (!triggers) {
+            reply.code(503).send({ error: "Trigger management is unavailable", code: "unavailable" });
+            return false;
+        }
+        return true;
+    };
+    // List a project's triggers (DTOs) + the picker catalog: the grantable tools, the
+    // events an event-trigger can fire on, and the trigger types — so the Triggers tab
+    // renders a precise capability + type picker without hard-coding them client-side
+    // (folds in the G4 `GRANTABLE_TOOLS` list).
+    app.get("/triggers", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "List a project's triggers plus the picker catalog",
+            description: "Returns the project's trigger DTOs together with the Triggers-tab picker catalog. " +
+                "Success (200) is an object with `triggers` (array of trigger DTOs, each combining the " +
+                "`trigger` when-clause, the `run` definition, `enabled`, and derived fields like `agentName`), " +
+                "`grantableTools` (the tools an event/webhook trigger may be granted), `events` (the lifecycle " +
+                "events an event trigger can fire on), and `triggerTypes` (the supported trigger kinds).",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                },
+                required: ["slug"],
+            },
+            response: {
+                200: {
+                    description: "The trigger DTO list plus picker catalog (`triggers`, `grantableTools`, `events`, `triggerTypes`).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        try {
+            const list = await triggers.list(req.params.slug); // throws not_found
+            return {
+                triggers: list,
+                grantableTools: GRANTABLE_TOOLS,
+                events: [...TRIGGER_EVENTS],
+                triggerTypes: [...TRIGGER_TYPES],
+            };
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Get one trigger by name (404 when the project declares no such trigger).
+    app.get("/triggers/:name", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "Get one trigger by name",
+            description: "Fetches a single trigger's config by name. Success (200) is an object with a `trigger` field " +
+                "holding the trigger DTO (`trigger` when-clause + `run` + `enabled` + derived fields). Returns 404 " +
+                "when the project declares no trigger with that name.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                    name: { type: "string", description: "Trigger name." },
+                },
+                required: ["slug", "name"],
+            },
+            response: {
+                200: {
+                    description: "An object with a `trigger` field holding the trigger DTO.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        const { slug, name } = req.params;
+        try {
+            const trigger = await triggers.get(slug, name); // throws not_found (project)
+            if (!trigger) {
+                return reply.code(404).send({ error: `No such trigger: ${name}`, code: "not_found" });
+            }
+            return { trigger };
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Create or replace one trigger (keyed by name). Persists to project.yaml, then
+    // arms it so it's immediately fireable. Enabling/disabling is this same route with
+    // `enabled` flipped (GG-3). The body is the FULL record `{ trigger, run, enabled }`
+    // — a full replace (unlike the self-MCP set_trigger, which patches partial edits).
+    app.put("/triggers/:name", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "Create or replace one trigger",
+            description: "Creates or fully replaces a trigger keyed by name, persisting it to project.yaml then arming it. " +
+                "Enabling/disabling is this same route with `enabled` flipped. The body is the FULL trigger record: " +
+                "`trigger` is the WHEN clause — a discriminated union on `trigger.type` (`schedule` with `cron` xor " +
+                "`interval`; `event` with an `on` value such as `onArchive`/`afterTurn`; `webhook` with a `path`, " +
+                "shape-reserved) — `run` is the shared agent-run definition (prompt/promptFile, model, tools, etc.), " +
+                "and `enabled` is the on/off flag. Success (200) is an object with a `trigger` field holding the " +
+                "persisted trigger DTO. Returns 400 for an invalid name or malformed trigger definition.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                    name: { type: "string", description: "Trigger name." },
+                },
+                required: ["slug", "name"],
+            },
+            body: {
+                // Documentation-only (no validation/coercion): accept any/empty body.
+                type: ["object", "null"],
+                additionalProperties: true,
+                properties: {
+                    trigger: {
+                        description: "The WHEN clause: a discriminated union on `trigger.type` (`schedule`/`event`/`webhook`) with type-specific fields.",
+                    },
+                    run: {
+                        description: "The WHAT clause: the shared agent-run definition (prompt/promptFile, model, tools, session mode, etc.).",
+                    },
+                    enabled: { description: "Whether the trigger is armed; new triggers default disabled." },
+                },
+            },
+            response: {
+                200: {
+                    description: "An object with a `trigger` field holding the persisted trigger DTO.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        const { slug, name } = req.params;
+        if (!isValidTriggerName(name)) {
+            return reply.code(400).send({ error: `Invalid trigger name: ${name}`, code: "invalid" });
+        }
+        // Reject a malformed record early (bad discriminant, both/neither cron+interval,
+        // unknown event, both/neither prompt+promptFile) so the client gets a 400
+        // instead of the store's generic error; TriggerService.set re-validates.
+        if (!sanitizeTrigger(req.body)) {
+            return reply.code(400).send({ error: "Invalid trigger definition", code: "invalid" });
+        }
+        try {
+            const trigger = await triggers.set(slug, name, req.body); // throws not_found/invalid
+            return { trigger };
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Delete one trigger. Removes it from project.yaml AND disarms it (an event
+    // trigger's agent is torn down; a schedule trigger's forwarded entry is dropped).
+    app.delete("/triggers/:name", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "Delete one trigger",
+            description: "Removes a trigger from project.yaml AND disarms it (an event trigger's agent is torn down; a " +
+                "schedule trigger's forwarded entry is dropped). Success (200) is an object with `ok: true`, the " +
+                "`name`, and `removed` describing what was removed.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                    name: { type: "string", description: "Trigger name." },
+                },
+                required: ["slug", "name"],
+            },
+            response: {
+                200: {
+                    description: "An object with `ok`, `name`, and `removed`.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        const { slug, name } = req.params;
+        try {
+            const removed = await triggers.remove(slug, name); // throws not_found (project)
+            return reply.code(200).send({ ok: true, name, removed });
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Per-trigger RUNTIME state (Epic T follow-up / #327) — the live "last-run / next-run
+    // / status" the Triggers tab renders alongside each trigger's config. `TriggerDto`
+    // carries config only, so this JOINS it with herdctl runtime state the tab lost when
+    // the Schedules section folded in: the cron scheduler's `ScheduleInfo` (next-fire,
+    // status — schedule triggers) + job records (last run, per the E3/#268 pattern) for
+    // each trigger's own scoped agent. Served as its OWN endpoint (not folded into the
+    // config list) so the tab can POLL it cheaply without re-fetching the config + picker
+    // catalog. A static path segment — matched before `/:name` — so no trigger shadows it.
+    app.get("/triggers/runtime", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "Live runtime state for a project's triggers",
+            description: "Per-trigger live last-run / next-run / status, joining each trigger's config with herdctl runtime " +
+                "state (the cron scheduler's next-fire + status for schedule triggers, plus job records for last run). " +
+                "This is a static path segment, matched BEFORE `/:name`, so no trigger name shadows it. It is served " +
+                "as its own pollable endpoint (separate from the config list). Success (200) is an object with a " +
+                "`runtime` field describing each trigger's live state.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                },
+                required: ["slug"],
+            },
+            response: {
+                200: {
+                    description: "An object with a `runtime` field describing each trigger's live last-run/next-run/status.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        try {
+            const project = await projects.get(req.params.slug); // throws not_found
+            const dtos = await triggers.list(project.slug);
+            // The agents a trigger's runs land under: the keeper (unscoped schedule
+            // triggers) + every trigger's own scoped `trigger-<slug>-<name>` agent.
+            const agents = [keeperAgentName(project.slug), ...dtos.map((d) => d.agentName)];
+            const [runs, schedules] = await Promise.all([
+                herdctl.listRunsForAgents(agents).catch(() => []),
+                herdctl.listAgentSchedules(project).catch(() => []),
+            ]);
+            return { runtime: buildTriggerRuntime(dtos, runs, schedules, project.slug) };
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+    // Fire a trigger NOW (Epic T follow-up / #327) — "Run now". Runs it through the same
+    // hub path a cron / event fire uses, so the resulting chat is a first-class, badged
+    // run (indistinguishable from an automatic fire). Fires ANY trigger type regardless
+    // of its `enabled` flag — a manual run is deliberate (mirrors the schedule DD-1 rule).
+    // 503 when the trigger fire entrypoint isn't wired (tests may omit it); 404 for an
+    // unknown trigger; 502 if the fire started no chat. Responds 202 with the session id.
+    app.post("/triggers/:name/run", {
+        schema: {
+            tags: ["Triggers"],
+            summary: "Run a trigger now",
+            description: "Fires a trigger immediately (\"Run now\") through the same hub path a cron/event fire uses, producing " +
+                "a first-class badged run. Fires any trigger type regardless of its `enabled` flag. Success is 202 with " +
+                "an object containing `ok: true`, the `name`, and the started `sessionId`. Returns 503 when firing is " +
+                "unavailable, 404 for an unknown trigger, 409 for the post-turn curator trigger (not runnable on demand), " +
+                "and 502 if the fire started no chat.",
+            params: {
+                type: "object",
+                properties: {
+                    slug: { type: "string", description: "Project slug." },
+                    name: { type: "string", description: "Trigger name." },
+                },
+                required: ["slug", "name"],
+            },
+            response: {
+                202: {
+                    description: "An object with `ok`, `name`, and the started `sessionId`.",
+                    type: "object",
+                    additionalProperties: true,
+                },
+            },
+        },
+    }, async (req, reply) => {
+        if (!triggersGuard(reply))
+            return reply;
+        const { slug, name } = req.params;
+        if (!fireTrigger) {
+            return reply.code(503).send({ error: "Trigger firing is unavailable", code: "unavailable" });
+        }
+        try {
+            const project = await projects.get(slug); // throws not_found
+            const rec = project.triggers?.[name];
+            if (!rec) {
+                return reply.code(404).send({ error: `No such trigger: ${name}`, code: "not_found" });
+            }
+            // The post-turn CURATOR (the folded-in sweeper — any `event`/`afterTurn` trigger,
+            // T5) is NOT a generic fireable trigger: it has no scoped `trigger-<slug>-<name>`
+            // agent (it runs via SweepService on the `afterTurn` event, needing a just-
+            // completed turn's context), so the generic fire path can't run it. Reject it with
+            // a clear 409 rather than letting the fire fail opaquely as a 502.
+            if (isCuratorTrigger(rec)) {
+                return reply.code(409).send({
+                    error: "The post-turn curator trigger runs automatically after each turn and can't be run on demand.",
+                    code: "not_runnable",
+                });
+            }
+            const sessionId = await fireTrigger(slug, name);
+            if (!sessionId) {
+                return reply
+                    .code(502)
+                    .send({ error: "Trigger fire did not start a chat", code: "trigger_failed" });
+            }
+            return reply.code(202).send({ ok: true, name, sessionId });
+        }
+        catch (err) {
+            return sendProjectError(reply, err);
+        }
+    });
+}

package/packages/server/dist/routes/workspace-mount.d.ts

@@ -0,0 +1,48 @@
+/**
+ * workspace-mount — the seam that makes the root workspace and a project
+ * workspace run literally the same route handlers.
+ *
+ * A workspace is identified by its path relative to `projectsRoot`, and the root
+ * workspace's key is the empty string (see `project-paths.ts`). An empty string
+ * cannot ride in a URL path segment — `/api/projects//chats` does not match — so
+ * rather than smuggle a sentinel like `__root` into the wire, the
+ * workspace-scoped routes are a Fastify plugin **registered twice**:
+ *
+ * | mount                   | workspace key    |
+ * |-------------------------|------------------|
+ * | `/api/root`             | `""`             |
+ * | `/api/projects/:slug`   | `params.slug`    |
+ *
+ * **This is the architectural guarantee, not a convenience.** "The root behaves
+ * exactly like a project" is true by construction — same handlers, same schemas,
+ * same error paths — instead of being a property someone has to remember to
+ * preserve. The previous design made the root a project with a reserved slug and
+ * then had to keep two resolution branches in step; one of them was missed and
+ * every root file route 404'd.
+ *
+ * Handlers are untouched by the split: they still read `req.params.slug`. On the
+ * root mount there is no `:slug` segment to match, so {@link rootParamsHook}
+ * injects `slug: ""` in `onRequest` — which runs BEFORE schema validation, so
+ * the existing `required: ["slug"]` params schemas keep validating unchanged.
+ * (Verified against Fastify directly rather than assumed.)
+ */
+import type { FastifyInstance } from "fastify";
+/** URL prefix for the root workspace's scoped routes. */
+export declare const ROOT_MOUNT_PREFIX = "/api/root";
+/** URL prefix (parametric) for a project workspace's scoped routes. */
+export declare const PROJECT_MOUNT_PREFIX = "/api/projects/:slug";
+/**
+ * Give the root mount the `slug` param its handlers and schemas expect.
+ *
+ * `onRequest` is deliberate: it is the earliest lifecycle hook, and in
+ * particular it runs before params validation, so a schema declaring
+ * `required: ["slug"]` still passes on a path that has no `:slug` segment.
+ */
+export declare function rootParamsHook(app: FastifyInstance): void;
+/**
+ * Register one workspace-scoped route group at both mounts.
+ *
+ * `group` is a plain Fastify plugin that declares its paths RELATIVE to the
+ * workspace (e.g. `/chats/:sessionId`, not `/api/projects/:slug/chats/:sessionId`).
+ */
+export declare function mountWorkspaceRoutes(app: FastifyInstance, group: (app: FastifyInstance) => void): Promise<void>;

package/packages/server/dist/routes/workspace-mount.js

@@ -0,0 +1,32 @@
+/** URL prefix for the root workspace's scoped routes. */
+export const ROOT_MOUNT_PREFIX = "/api/root";
+/** URL prefix (parametric) for a project workspace's scoped routes. */
+export const PROJECT_MOUNT_PREFIX = "/api/projects/:slug";
+/**
+ * Give the root mount the `slug` param its handlers and schemas expect.
+ *
+ * `onRequest` is deliberate: it is the earliest lifecycle hook, and in
+ * particular it runs before params validation, so a schema declaring
+ * `required: ["slug"]` still passes on a path that has no `:slug` segment.
+ */
+export function rootParamsHook(app) {
+    app.addHook("onRequest", (req, _reply, done) => {
+        req.params = { ...(req.params ?? {}), slug: "" };
+        done();
+    });
+}
+/**
+ * Register one workspace-scoped route group at both mounts.
+ *
+ * `group` is a plain Fastify plugin that declares its paths RELATIVE to the
+ * workspace (e.g. `/chats/:sessionId`, not `/api/projects/:slug/chats/:sessionId`).
+ */
+export async function mountWorkspaceRoutes(app, group) {
+    await app.register(async (scoped) => {
+        rootParamsHook(scoped);
+        group(scoped);
+    }, { prefix: ROOT_MOUNT_PREFIX });
+    await app.register(async (scoped) => {
+        group(scoped);
+    }, { prefix: PROJECT_MOUNT_PREFIX });
+}

package/packages/server/dist/routes.d.ts

@@ -0,0 +1,26 @@
+/**
+ * REST routes — composition root.
+ *
+ * The Fastify REST surface is one `registerRoutes(app, deps)` that builds the
+ * shared route context once (see {@link buildRouteContext}) and then hangs each
+ * per-group cluster off the app via a `registerXRoutes(app, ctx)` call. The
+ * handlers themselves live in the sibling group modules; the pure DTO/HTTP
+ * helpers live in `chat-dto.ts` / `http-bytes.ts` / `route-errors.ts` (issue
+ * #403 — break up oversized files). Each group registers directly off `app`
+ * (no Fastify plugins), preserving the original wiring shape.
+ *
+ * The route map, by group:
+ *   meta     — /api/transcription, /api/transcribe, /api/me, /api/health,
+ *              /api/instance-config, /api/models, /api/fleet,
+ *              /api/chat-files/:id, project chat upload
+ *   git      — /api/git[/push|/github/*], project git status/diff/commit
+ *   projects — projects CRUD + promote, pins, files/changelog/overview/commands
+ *   triggers — project triggers CRUD + runtime + run-now
+ *   chats    — workspace chat lifecycle (list/runs/usage/create/messages/
+ *              subagents/context/delete/rename/fork/archive/star/seen/promote)
+ */
+import type { FastifyInstance } from "fastify";
+import { type RouteDeps } from "./route-context.js";
+export type { RouteDeps } from "./route-context.js";
+export { parseRangeHeader } from "./http-bytes.js";
+export declare function registerRoutes(app: FastifyInstance, deps: RouteDeps): Promise<void>;

package/packages/server/dist/routes.js

@@ -0,0 +1,29 @@
+import { buildRouteContext } from "./route-context.js";
+import { registerMetaRoutes, registerMetaWorkspaceRoutes } from "./routes/meta.js";
+import { registerGitRoutes, registerGitWorkspaceRoutes } from "./routes/git.js";
+import { registerProjectRoutes, registerProjectWorkspaceRoutes } from "./routes/projects.js";
+import { registerTriggerWorkspaceRoutes } from "./routes/triggers.js";
+import { registerChatWorkspaceRoutes } from "./routes/chats.js";
+import { registerMcpRoutes } from "./routes/mcp.js";
+import { mountWorkspaceRoutes } from "./routes/workspace-mount.js";
+export { parseRangeHeader } from "./http-bytes.js";
+export async function registerRoutes(app, deps) {
+    const ctx = buildRouteContext(deps);
+    registerMetaRoutes(app, ctx);
+    registerGitRoutes(app, ctx);
+    registerProjectRoutes(app, ctx);
+    // The workspace-scoped half of every group, mounted twice: `/api/root` (the
+    // root workspace, key `""`) and `/api/projects/:slug` (a project). Same
+    // handlers both times — that identity is the point, not an optimisation.
+    await mountWorkspaceRoutes(app, (scoped) => {
+        registerProjectWorkspaceRoutes(scoped, ctx);
+        registerChatWorkspaceRoutes(scoped, ctx);
+        registerGitWorkspaceRoutes(scoped, ctx);
+        registerTriggerWorkspaceRoutes(scoped, ctx);
+        registerMetaWorkspaceRoutes(scoped, ctx);
+    });
+    // #312 M1: the external Management API gate. Registered unconditionally (it
+    // answers 404 when unconfigured) so an unconfigured `/mcp` can never fall
+    // through to the SPA not-found handler and be served the app shell.
+    registerMcpRoutes(app, ctx);
+}

package/packages/server/dist/run-provenance.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Every origin, as VALUES — the single source of truth for both the type and the
+ * runtime allowlist {@link coerce} validates against.
+ *
+ * Declared this way round on purpose (#588). It used to be a hand-written union
+ * with a separate `readonly TurnOrigin[]` list, and `readonly TurnOrigin[]` only
+ * asserts that each element IS an origin — never that every origin is an
+ * element. So when the union grew, the allowlist silently lagged: `coerce()`
+ * returned null for the new member, and every chat carrying it lost BOTH its
+ * badge and its parent edge on read, with no error anywhere. Deriving the type
+ * from the list makes that impossible rather than merely documented.
+ */
+export declare const ORIGINS: readonly ["human", "scheduled", "spawned", "hook", "adopted"];
+/**
+ * How a turn/chat came to exist — the provenance dimension #267 badges on.
+ *
+ * `adopted` (#588) is the odd one out: the chat was not created by Paddock at
+ * all. It is a terminal `claude` session the user ran themselves and later
+ * imported, so it has no creating turn, no parent, and nothing ever "ran" it
+ * here. It is therefore a ROOT and it is ATTENDED — see `ORIGIN_IS_ROOT` in
+ * ./chat-dto.ts and `ORIGIN_IS_UNATTENDED` in ./runs.ts, both of which are
+ * `Record<TurnOrigin, boolean>` so that adding a member here forces a
+ * DECISION at each of them instead of a silent fallthrough.
+ */
+export type TurnOrigin = (typeof ORIGINS)[number];
+/** A chat's provenance marker: how it was created + how deep in a spawn tree. */
+export interface RunProvenance {
+    origin: TurnOrigin;
+    /** Spawn hops from the human/scheduled root (0 = root). #262 gates on this. */
+    depth: number;
+    /**
+     * The chat that CREATED this one — the parent edge the nested chat list draws.
+     * `depth` alone says a chat was spawned and how deep, but never BY WHOM, so the
+     * list could badge a child yet not file it under its parent.
+     *
+     * Absent for roots, for chats created before this field existed, and for the
+     * external `/mcp` transport (no calling chat). Historical chats are backfilled
+     * at read time from MessageProvenanceStore — see `parentChat()` there.
+     */
+    parentSessionId?: string;
+    /** The parent's project slug — a parent can live in ANOTHER project. */
+    parentProject?: string;
+}
+/** A reference to the chat that created another one. */
+export interface ParentChatRef {
+    project: string;
+    sessionId: string;
+}
+/** The root of any chat tree a human starts: origin `human`, depth 0. */
+export declare const HUMAN_ROOT: RunProvenance;
+/**
+ * A schedule-fired chat: origin `scheduled`, depth 0. A cron is a root trigger,
+ * exactly like a human — there is no scheduler wired yet (that's Epic D), but the
+ * marker path accepts it now.
+ */
+export declare const SCHEDULED_ROOT: RunProvenance;
+/**
+ * An IMPORTED terminal chat (#588): origin `adopted`, depth 0.
+ *
+ * Depth 0 because the session was never spawned by anything in this instance —
+ * the user ran it themselves in a terminal and Paddock only adopted the
+ * transcript. Stamped with `stampIfAbsent`, never `stamp`: if a chat somehow
+ * already carries a marker, whatever created it here knows more about its
+ * origin than the import does.
+ */
+export declare const ADOPTED_ROOT: RunProvenance;
+/**
+ * The provenance a child inherits when `parent` spawns it via a self-MCP write
+ * tool: origin becomes `spawned` and depth is one deeper. So a fan-out tree's
+ * depth is always the number of spawn hops from its human/scheduled root, which
+ * is exactly what #262 bounds with `maxSpawnDepth`.
+ */
+export declare function childOf(parent: RunProvenance, parentRef?: ParentChatRef | null): RunProvenance;
+export declare class RunProvenanceStore {
+    private readonly stateFile;
+    /** In-memory map of sessionId -> provenance (loaded once, written through). */
+    private state;
+    /**
+     * The in-flight load, cached so concurrent first-callers share ONE read.
+     * Caching only the resolved `state` would let several stamps that begin before
+     * the first `fs.readFile` resolves each build their own map and race on the
+     * assignment — a lost update (last writer's map wins, dropping the others'
+     * keys). Reachable when a keeper spawns several children right after startup.
+     */
+    private loadPromise;
+    /** Serialises concurrent writes so the file never interleaves. */
+    private writing;
+    constructor(dataDir: string);
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    private ensureLoaded;
+    /** This chat's recorded provenance, or undefined if none. Non-throwing. */
+    get(sessionId: string): Promise<RunProvenance | undefined>;
+    /**
+     * Record a chat's provenance. Idempotent (a repeat of the same marker is a
+     * no-op), and a blank/unsafe session id or malformed marker is ignored. Callers
+     * stamp a chat when they CREATE it, so this is a fresh key in practice; it does
+     * overwrite if called again (unlike {@link stampIfAbsent}).
+     */
+    stamp(sessionId: string, provenance: RunProvenance): Promise<void>;
+    /**
+     * Record provenance ONLY if this chat has none yet — never clobbers an existing
+     * marker. Used on resume/wake paths (a scheduler wake resumes a chat that may
+     * already have been created by a human or a spawn), so its creation provenance
+     * survives.
+     */
+    stampIfAbsent(sessionId: string, provenance: RunProvenance): Promise<void>;
+    /** Write-through, serialised so overlapping stamps can't corrupt the file. */
+    private persist;
+}