@edspencer/paddock 0.0.1 → 0.56.0

package/packages/server/dist/run-provenance.js

@@ -0,0 +1,206 @@
+/**
+ * RunProvenanceStore — a Paddock-side sidecar recording HOW each chat was
+ * created: its provenance `origin` (human / scheduled / spawned) and its spawn
+ * `depth` within a fan-out tree. This is the FOUNDATION marker for the
+ * Events / Schedules / Config initiative (issue #261 / design decisions DD-3,
+ * DD-6). Later tickets read it:
+ *   - #262 reads a chat's `depth` to gate whether it may spawn children (the
+ *     fork-bomb bound: inject the self-MCP write tools iff depth < maxSpawnDepth).
+ *   - #267 reads a chat's `origin` to badge it (human / scheduled / spawned) in
+ *     the chat list.
+ *
+ * This ticket (A1) only CARRIES and PERSISTS the marker — nothing gates on it
+ * yet, and spawn behaviour is unchanged.
+ *
+ * Shape: a `sessionId -> { origin, depth }` map persisted as a plain JSON object
+ * — the exact ArchiveStore / ReadStateStore sidecar pattern (lazy-loaded,
+ * write-through, serialised, corruption-tolerant, `0o600`). Provenance is
+ * low-sensitivity but there's no reason for it to be world-readable.
+ *
+ * Semantics: provenance describes how a chat was CREATED, so it is stamped once —
+ * at creation — and is NEVER clobbered by a later turn. Resuming, waking, or
+ * `send_message`-ing an existing chat leaves its recorded provenance intact.
+ * Callers use {@link RunProvenanceStore.stamp} at the point they create a chat and
+ * {@link RunProvenanceStore.stampIfAbsent} on paths that may resume an
+ * already-known chat (e.g. a scheduler wake), so an established marker can't be
+ * overwritten.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "run-provenance.json";
+/**
+ * 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 const ORIGINS = ["human", "scheduled", "spawned", "hook", "adopted"];
+/** The root of any chat tree a human starts: origin `human`, depth 0. */
+export const HUMAN_ROOT = { origin: "human", depth: 0 };
+/**
+ * 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 const SCHEDULED_ROOT = { origin: "scheduled", depth: 0 };
+/**
+ * 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 const ADOPTED_ROOT = { origin: "adopted", depth: 0 };
+/**
+ * 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 function childOf(parent, parentRef) {
+    return {
+        origin: "spawned",
+        depth: parent.depth + 1,
+        // Record WHICH chat spawned it, when the caller knows. Optional so every
+        // existing `childOf(p)` call site stays correct (just without the edge).
+        ...(parentRef?.sessionId
+            ? { parentSessionId: parentRef.sessionId, parentProject: parentRef.project }
+            : {}),
+    };
+}
+function isOrigin(v) {
+    return typeof v === "string" && ORIGINS.includes(v);
+}
+/** A session id we're willing to key on — mirrors attributeRunningSession's guard. */
+function isSafeId(sessionId) {
+    return typeof sessionId === "string" && /^[A-Za-z0-9._-]+$/.test(sessionId);
+}
+/** Validate + normalize an untrusted value into a RunProvenance, or null. */
+function coerce(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const o = value;
+    if (!isOrigin(o.origin))
+        return null;
+    const depth = o.depth;
+    if (typeof depth !== "number" || !Number.isFinite(depth) || depth < 0)
+        return null;
+    // The parent edge is optional and only carried when BOTH halves survive
+    // validation — a session id without its project can't be resolved to a chat.
+    const parentSessionId = typeof o.parentSessionId === "string" && isSafeId(o.parentSessionId)
+        ? o.parentSessionId
+        : undefined;
+    const parentProject = typeof o.parentProject === "string" ? o.parentProject : undefined;
+    return {
+        origin: o.origin,
+        depth: Math.floor(depth),
+        // `parentProject` is a workspace key; `""` is the ROOT workspace, not
+        // "missing". Test for presence, not truthiness, or a root chat's children
+        // lose their recorded parent edge on every parse.
+        ...(parentSessionId && parentProject !== undefined
+            ? { parentSessionId, parentProject }
+            : {}),
+    };
+}
+export class RunProvenanceStore {
+    stateFile;
+    /** In-memory map of sessionId -> provenance (loaded once, written through). */
+    state = null;
+    /**
+     * 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.
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.state)
+            return Promise.resolve(this.state);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                const map = new Map();
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            const p = coerce(v);
+                            if (p)
+                                map.set(k, p);
+                        }
+                    }
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.state = map;
+                return map;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** This chat's recorded provenance, or undefined if none. Non-throwing. */
+    async get(sessionId) {
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(sessionId);
+    }
+    /**
+     * 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}).
+     */
+    async stamp(sessionId, provenance) {
+        if (!isSafeId(sessionId))
+            return;
+        const p = coerce(provenance);
+        if (!p)
+            return;
+        const map = await this.ensureLoaded();
+        const prev = map.get(sessionId);
+        if (prev && prev.origin === p.origin && prev.depth === p.depth)
+            return; // no-op
+        map.set(sessionId, p);
+        await this.persist(map);
+    }
+    /**
+     * 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.
+     */
+    async stampIfAbsent(sessionId, provenance) {
+        if (!isSafeId(sessionId))
+            return;
+        const map = await this.ensureLoaded();
+        if (map.has(sessionId))
+            return;
+        await this.stamp(sessionId, provenance);
+    }
+    /** Write-through, serialised so overlapping stamps can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}

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

@@ -0,0 +1,92 @@
+/**
+ * Run-history DTO builder (E3 / #268 / DD-6) — the "while you were away" view.
+ *
+ * A *run* is one herdctl job record (a keeper turn written by a batch
+ * `trigger()`): it carries timing (`started_at`/`finished_at`/`duration_seconds`),
+ * `status`, `session_id`, and the schedule/fork that triggered it. This module
+ * JOINS those raw records with Paddock's {@link RunProvenanceStore} marker so
+ * each run reports its true origin — **human / scheduled / spawned** — plus the
+ * spawn `depth`. Provenance is authoritative here: paddock-initiated turns still
+ * persist `trigger_type:"manual"` on the job record (see ws.ts), so the
+ * scheduled/spawned distinction lives in the provenance store, not in the enum.
+ *
+ * The build step is deliberately PURE (no I/O): the route resolves the job
+ * records ({@link HerdctlService.listProjectRuns}), the provenance map, and the
+ * per-user "runs last seen" watermark, then hands them here. That keeps the
+ * join, the since-last-visit split, and the cost seam unit-testable.
+ *
+ * **Cost is P3 (deferred to X1/#378 + X2/#271).** herdctl does not yet persist
+ * per-run token accounting on the job record, so {@link RunSummary.cost} is a
+ * documented seam that is ALWAYS `null` today; when the accounting lands it slots
+ * in here without touching the wire shape.
+ */
+import type { JobMetadata } from "@herdctl/core";
+import type { RunProvenance, TurnOrigin } from "./run-provenance.js";
+/**
+ * Per-run cost, priced from herdctl's persisted per-model token accounting
+ * (DD-4). A SEAM only — always `null` until X1/#378 (herdctl persists the
+ * tokens) + X2/#271 (Paddock prices them) land. Shape reserved so adding it is
+ * additive.
+ */
+export interface RunCost {
+    /** Total cost in USD across every model the run touched. */
+    usd: number;
+    /** Whether `usd` is a real SDK figure or a CLI/Max-plan estimate. */
+    estimated: boolean;
+}
+/** One row in the run-history view: a job record joined with its provenance. */
+export interface RunSummary {
+    /** herdctl job id (`job-YYYY-MM-DD-<rand>`); stable per run. */
+    jobId: string;
+    /** The chat this run belongs to (link target), or null if unresolved. */
+    sessionId: string | null;
+    /** How the run came to exist (provenance marker; `human` when unmarked). */
+    origin: TurnOrigin;
+    /** Spawn hops from the human/scheduled root (0 = root). */
+    depth: number;
+    /** herdctl's persisted trigger type — a secondary signal (see module note). */
+    triggerType: string;
+    /** Schedule name that fired this run, when scheduled. */
+    schedule: string | null;
+    /** Parent job id, when this run was forked from another. */
+    forkedFrom: string | null;
+    /** Terminal/live status: completed | failed | cancelled | running | pending. */
+    status: string;
+    /** Why it exited (success | error | max_turns | timeout | cancelled), if done. */
+    exitReason: string | null;
+    /** ISO timestamp the run started. */
+    startedAt: string;
+    /** ISO timestamp the run finished, or null while running. */
+    finishedAt: string | null;
+    /** Wall-clock seconds, or null while running / unrecorded. */
+    durationSeconds: number | null;
+    /** The prompt the run was given (truncation is the client's job). */
+    prompt: string | null;
+    /** The agent's own one-line summary of the run, when it wrote one. */
+    summary: string | null;
+    /**
+     * True when the run completed AFTER the viewer's "runs last seen" watermark —
+     * i.e. it happened while they were away. Drives the since-last-visit digest.
+     */
+    isNew: boolean;
+    /** Per-run cost — P3 seam, always null today (see {@link RunCost}). */
+    cost: RunCost | null;
+}
+/** The payload the run-history endpoint returns. */
+export interface ProjectRuns {
+    runs: RunSummary[];
+    /** Epoch-ms the viewer last visited the run-history view (0 = never). */
+    lastSeen: number;
+    /** Count of unattended (scheduled + spawned) runs newer than `lastSeen`. */
+    newUnattended: number;
+}
+/** A run is "unattended" when a schedule or another chat — not a human — ran it. */
+export declare function isUnattended(origin: TurnOrigin): boolean;
+/**
+ * Join raw job records with the provenance map and the viewer's watermark into
+ * the wire DTO. `jobs` is expected most-recent-first (as `listJobs` returns);
+ * order is preserved. `provenanceBySession` maps a session id to its marker;
+ * a missing entry (or a null session id) defaults to `human`/depth 0. Runs that
+ * completed after `lastSeenMs` are flagged `isNew`.
+ */
+export declare function buildProjectRuns(jobs: JobMetadata[], provenanceBySession: ReadonlyMap<string, RunProvenance>, lastSeenMs: number): ProjectRuns;

package/packages/server/dist/runs.js

@@ -0,0 +1,72 @@
+/**
+ * Which origins ran WITHOUT the user watching — the "while you were away"
+ * digest's whole basis.
+ *
+ * A total `Record`, not a predicate with an `||` chain: a missing key is a
+ * compile error, so adding an origin forces a decision here instead of quietly
+ * defaulting. It must never become `origin !== "human"`, which reads the same
+ * today and is wrong tomorrow — `adopted` (#588) is a session the user ran
+ * themselves in a terminal and later imported, so one import of 22 sessions
+ * would announce "22 runs happened while you were away", the exact opposite of
+ * the truth.
+ */
+const ORIGIN_IS_UNATTENDED = {
+    human: false,
+    scheduled: true,
+    spawned: true,
+    hook: false,
+    adopted: false,
+};
+/** A run is "unattended" when a schedule or another chat — not a human — ran it. */
+export function isUnattended(origin) {
+    return ORIGIN_IS_UNATTENDED[origin] === true;
+}
+/**
+ * The epoch-ms a run "completed" for since-last-visit purposes: its finish time
+ * when it has one, else its start time (a still-running run counts as new the
+ * moment it starts). Returns 0 for an unparseable timestamp so it never spuriously
+ * counts as new.
+ */
+function completionMs(job) {
+    const iso = job.finished_at ?? job.started_at;
+    const ms = iso ? Date.parse(iso) : NaN;
+    return Number.isFinite(ms) ? ms : 0;
+}
+/**
+ * Join raw job records with the provenance map and the viewer's watermark into
+ * the wire DTO. `jobs` is expected most-recent-first (as `listJobs` returns);
+ * order is preserved. `provenanceBySession` maps a session id to its marker;
+ * a missing entry (or a null session id) defaults to `human`/depth 0. Runs that
+ * completed after `lastSeenMs` are flagged `isNew`.
+ */
+export function buildProjectRuns(jobs, provenanceBySession, lastSeenMs) {
+    let newUnattended = 0;
+    const runs = jobs.map((job) => {
+        const sessionId = job.session_id ?? null;
+        const prov = sessionId ? provenanceBySession.get(sessionId) : undefined;
+        const origin = prov?.origin ?? "human";
+        const depth = prov?.depth ?? 0;
+        const isNew = completionMs(job) > lastSeenMs;
+        if (isNew && isUnattended(origin))
+            newUnattended += 1;
+        return {
+            jobId: job.id,
+            sessionId,
+            origin,
+            depth,
+            triggerType: job.trigger_type,
+            schedule: job.schedule ?? null,
+            forkedFrom: job.forked_from ?? null,
+            status: job.status,
+            exitReason: job.exit_reason ?? null,
+            startedAt: job.started_at,
+            finishedAt: job.finished_at ?? null,
+            durationSeconds: job.duration_seconds ?? null,
+            prompt: job.prompt ?? null,
+            summary: job.summary ?? null,
+            isNew,
+            cost: null, // P3 seam — see RunCost
+        };
+    });
+    return { runs, lastSeen: lastSeenMs, newUnattended };
+}

package/packages/server/dist/schedule-config.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Scheduled-chat config helpers (issue #265 / DD-2).
+ *
+ * A Paddock schedule IS herdctl's `ScheduleSchema` shape, passed through the stack
+ * **unmolested** — the same field names herdctl's cron engine already reads, so a
+ * `schedules` block on the keeper agent config is armed with no translation. This
+ * module holds the small, pure surface around that pass-through:
+ *
+ *  - {@link sanitizeSchedules} — validate/normalise a hand-edited `project.yaml`
+ *    `schedules` map, DROPPING malformed entries so one bad edit can't brick the
+ *    keeper's `addAgent` registration (which would throw on an invalid schedule).
+ *
+ * The `schedules` block itself is now declared only via unified TRIGGERS
+ * (trigger-config.ts forwards SCHEDULE-type triggers into the keeper agent); this
+ * module retains only the back-compat parser for any legacy `schedules:` block still
+ * present in a hand-edited `project.yaml`.
+ */
+/**
+ * A scheduled chat declaration — herdctl's `ScheduleSchema` shape (same field
+ * names) plus the Paddock-only {@link PaddockSchedule.promptFile}. v1 arms the two
+ * timer types (`cron` / `interval`); herdctl's schema also defines `webhook` /
+ * `chat`, left out here since Paddock only schedules timers.
+ */
+export interface PaddockSchedule {
+    /** `cron` (5-field/`@daily` expression) or `interval` (e.g. `"30m"`, `"1h"`). */
+    type: "cron" | "interval";
+    /** The cron expression — required when `type: cron`. */
+    cron?: string;
+    /** The interval string (e.g. `"15m"`) — required when `type: interval`. */
+    interval?: string;
+    /**
+     * The inline prompt the scheduled turn runs. A schedule may instead point at a
+     * {@link promptFile}, which Paddock resolves to a prompt at fire time (so herdctl
+     * only ever receives a plain `prompt`). When both are set the file wins.
+     */
+    prompt?: string;
+    /** Whether the schedule is armed. Defaults true (herdctl's default). */
+    enabled?: boolean;
+    /**
+     * New-vs-accrete (DD-2). `false` (default) → a FRESH chat every fire; `true` →
+     * resume the schedule's ONE owned session (created on first fire, reused after),
+     * so a "manager" accretes one transcript.
+     */
+    resume_session?: boolean;
+    /**
+     * PADDOCK-ONLY convenience (DD-2): a git-tracked, keeper-editable prompt file
+     * under the project's `.paddock/schedules/` dir (e.g. `"daily-manager.md"`),
+     * relative to that dir. Read at fire time and forwarded as the schedule's
+     * `prompt`. NEVER forwarded into the herdctl config (kept pure). Traversal
+     * outside `.paddock/schedules/` and non-`.md` names are rejected.
+     */
+    promptFile?: string;
+}
+/** A schedule name we're willing to key on (also a safe herdctl schedule key). */
+export declare function isValidScheduleName(name: string): boolean;
+/**
+ * Validate + normalise one untrusted schedule record into a {@link PaddockSchedule},
+ * or `null` if it's malformed. A `cron` schedule MUST carry a `cron`; an `interval`
+ * one MUST carry an `interval` (herdctl would reject a type/field mismatch, so we
+ * drop it here rather than let `addAgent` throw and take the whole keeper down).
+ */
+export declare function sanitizeSchedule(raw: unknown): PaddockSchedule | null;
+/**
+ * Sanitise a whole `schedules` map, dropping malformed entries and entries with an
+ * unsafe name. Returns `undefined` when nothing survives (so it stays absent on
+ * disk / off the agent config).
+ */
+export declare function sanitizeSchedules(raw: unknown): Record<string, PaddockSchedule> | undefined;

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

@@ -0,0 +1,75 @@
+/**
+ * Scheduled-chat config helpers (issue #265 / DD-2).
+ *
+ * A Paddock schedule IS herdctl's `ScheduleSchema` shape, passed through the stack
+ * **unmolested** — the same field names herdctl's cron engine already reads, so a
+ * `schedules` block on the keeper agent config is armed with no translation. This
+ * module holds the small, pure surface around that pass-through:
+ *
+ *  - {@link sanitizeSchedules} — validate/normalise a hand-edited `project.yaml`
+ *    `schedules` map, DROPPING malformed entries so one bad edit can't brick the
+ *    keeper's `addAgent` registration (which would throw on an invalid schedule).
+ *
+ * The `schedules` block itself is now declared only via unified TRIGGERS
+ * (trigger-config.ts forwards SCHEDULE-type triggers into the keeper agent); this
+ * module retains only the back-compat parser for any legacy `schedules:` block still
+ * present in a hand-edited `project.yaml`.
+ */
+const SCHEDULE_TYPES = new Set(["cron", "interval"]);
+/** A schedule name we're willing to key on (also a safe herdctl schedule key). */
+export function isValidScheduleName(name) {
+    return typeof name === "string" && /^[A-Za-z0-9._-]+$/.test(name) && name.length <= 64;
+}
+/**
+ * Validate + normalise one untrusted schedule record into a {@link PaddockSchedule},
+ * or `null` if it's malformed. A `cron` schedule MUST carry a `cron`; an `interval`
+ * one MUST carry an `interval` (herdctl would reject a type/field mismatch, so we
+ * drop it here rather than let `addAgent` throw and take the whole keeper down).
+ */
+export function sanitizeSchedule(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    const type = o.type;
+    if (typeof type !== "string" || !SCHEDULE_TYPES.has(type))
+        return null;
+    const out = { type: type };
+    if (type === "cron") {
+        if (typeof o.cron !== "string" || o.cron.trim() === "")
+            return null;
+        out.cron = o.cron.trim();
+    }
+    else {
+        if (typeof o.interval !== "string" || o.interval.trim() === "")
+            return null;
+        out.interval = o.interval.trim();
+    }
+    if (typeof o.prompt === "string")
+        out.prompt = o.prompt;
+    if (typeof o.enabled === "boolean")
+        out.enabled = o.enabled;
+    if (typeof o.resume_session === "boolean")
+        out.resume_session = o.resume_session;
+    if (typeof o.promptFile === "string" && o.promptFile.trim() !== "") {
+        out.promptFile = o.promptFile.trim();
+    }
+    return out;
+}
+/**
+ * Sanitise a whole `schedules` map, dropping malformed entries and entries with an
+ * unsafe name. Returns `undefined` when nothing survives (so it stays absent on
+ * disk / off the agent config).
+ */
+export function sanitizeSchedules(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const out = {};
+    for (const [name, val] of Object.entries(raw)) {
+        if (!isValidScheduleName(name))
+            continue;
+        const s = sanitizeSchedule(val);
+        if (s)
+            out[name] = s;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}

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

@@ -0,0 +1,34 @@
+export declare class ScheduleSessionStore {
+    private readonly stateFile;
+    /** In-memory map of `<slug>\0<scheduleName>` -> 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 schedule owns, or undefined if it hasn't fired yet. Non-throwing. */
+    get(slug: string, scheduleName: string): Promise<string | undefined>;
+    /**
+     * Record the session a schedule 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, scheduleName: string, sessionId: string): Promise<void>;
+    /**
+     * Forget a schedule's owned session — used when the recorded transcript has
+     * vanished (so the next fire re-creates one) or the schedule was removed. No-op
+     * if there was nothing recorded.
+     */
+    clear(slug: string, scheduleName: string): Promise<void>;
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    private persist;
+}

package/packages/server/dist/schedule-session.js

@@ -0,0 +1,120 @@
+/**
+ * ScheduleSessionStore — a Paddock-side sidecar mapping an *accreting* schedule
+ * to the ONE chat session it owns (issue #265 / DD-2). A schedule declared with
+ * `resume_session: true` should build up a single long-lived transcript across
+ * every fire (a "manager" that accretes context), rather than spawning a fresh
+ * chat each time. To make that resume unambiguous, Paddock records the session id
+ * the schedule created on its FIRST fire and reuses it thereafter.
+ *
+ * Chosen over "resume the latest chat of a lineage" (DD-2, resolved decision #1):
+ * a stable owned id is unambiguous and survives new chats a human might start in
+ * the same project. A `resume_session: false` schedule owns nothing — it gets a
+ * new chat every fire and never touches this store.
+ *
+ * Shape + concurrency: a `"<slug>\0<scheduleName>" -> sessionId` map persisted as
+ * a plain JSON object — the exact ArchiveStore / ReadStateStore / RunProvenanceStore
+ * sidecar pattern (lazy-loaded, write-through, serialised, corruption-tolerant,
+ * `0o600`), INCLUDING the in-flight-load-promise fix: `ensureLoaded` caches the
+ * load PROMISE (not just the resolved map) so concurrent first-callers share one
+ * read and can't each build a separate map and race on the assignment (a lost
+ * update). Reachable if several schedules fire in the same tick right after boot.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+const STATE_FILE = "schedule-sessions.json";
+/** The composite key separator — NUL can't appear in a slug or schedule name. */
+const SEP = "\0";
+/** A session id we're willing to key on — mirrors RunProvenanceStore's guard. */
+function isSafeId(sessionId) {
+    return typeof sessionId === "string" && /^[A-Za-z0-9._-]+$/.test(sessionId);
+}
+export class ScheduleSessionStore {
+    stateFile;
+    /** In-memory map of `<slug>\0<scheduleName>` -> owned sessionId. */
+    state = null;
+    /**
+     * 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.
+     */
+    loadPromise = null;
+    /** Serialises concurrent writes so the file never interleaves. */
+    writing = Promise.resolve();
+    constructor(dataDir) {
+        this.stateFile = path.join(dataDir, STATE_FILE);
+    }
+    static key(slug, scheduleName) {
+        return `${slug}${SEP}${scheduleName}`;
+    }
+    /** Load the persisted map (lazily, deduped; tolerant of a missing/corrupt file). */
+    ensureLoaded() {
+        if (this.state)
+            return Promise.resolve(this.state);
+        if (!this.loadPromise) {
+            this.loadPromise = (async () => {
+                const map = new Map();
+                try {
+                    const raw = await fs.readFile(this.stateFile, "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+                        for (const [k, v] of Object.entries(parsed)) {
+                            if (typeof v === "string" && isSafeId(v))
+                                map.set(k, v);
+                        }
+                    }
+                }
+                catch {
+                    /* missing or unreadable — start empty */
+                }
+                this.state = map;
+                return map;
+            })();
+        }
+        return this.loadPromise;
+    }
+    /** The session id this schedule owns, or undefined if it hasn't fired yet. Non-throwing. */
+    async get(slug, scheduleName) {
+        const map = await this.ensureLoaded().catch(() => new Map());
+        return map.get(ScheduleSessionStore.key(slug, scheduleName));
+    }
+    /**
+     * Record the session a schedule 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).
+     */
+    async set(slug, scheduleName, sessionId) {
+        if (!isSafeId(sessionId))
+            return;
+        const key = ScheduleSessionStore.key(slug, scheduleName);
+        const map = await this.ensureLoaded();
+        if (map.get(key) === sessionId)
+            return; // no-op
+        map.set(key, sessionId);
+        await this.persist(map);
+    }
+    /**
+     * Forget a schedule's owned session — used when the recorded transcript has
+     * vanished (so the next fire re-creates one) or the schedule was removed. No-op
+     * if there was nothing recorded.
+     */
+    async clear(slug, scheduleName) {
+        const key = ScheduleSessionStore.key(slug, scheduleName);
+        const map = await this.ensureLoaded();
+        if (!map.has(key))
+            return;
+        map.delete(key);
+        await this.persist(map);
+    }
+    /** Write-through, serialised so overlapping writes can't corrupt the file. */
+    persist(map) {
+        this.writing = this.writing.then(async () => {
+            const obj = {};
+            for (const [k, v] of map)
+                obj[k] = v;
+            const json = JSON.stringify(obj, null, 2);
+            await fs.writeFile(this.stateFile, json, { encoding: "utf8", mode: 0o600 }).catch(() => undefined);
+        });
+        return this.writing;
+    }
+}