@edspencer/paddock 0.65.0 → 0.66.1

package/packages/server/dist/schema-version.js

@@ -0,0 +1,142 @@
+/**
+ * Schema versioning for the two on-disk formats paddock OWNS (issue #724).
+ *
+ * Those two are `project.yaml` and `paddock.config.yaml`, and only those two.
+ * The `version: 1` fields elsewhere in the tree belong to herdctl — its fleet
+ * config (`herdctl-agent-config.ts`) and `@herdctl/core`'s session metadata —
+ * and transcripts are Claude Code's format. Paddock reads neither back.
+ *
+ * ## What this is for: the DOWNGRADE guard, not migrations
+ *
+ * There is no migration runner here, deliberately (#724, and #717 for the
+ * sequencing). With `1` as the only version there is nothing to migrate, and a
+ * runner with zero migrations cannot be meaningfully tested.
+ *
+ * The value delivered on its own is the guard. Running an OLDER paddock against
+ * a data dir a newer one wrote — `npx @edspencer/paddock@0.62.0` is one command
+ * away — lenient-parses it: `ProjectStore.normalize` drops every key it does not
+ * recognise, and the next `update()` writes the file back without them. A
+ * `path:` or a `managed:` disappears with no error. A declared version turns
+ * that into "this file is version 4, I understand 1, I am not touching it".
+ *
+ * **Never lenient-parse a file from the future.** That is the whole point.
+ *
+ * ## Adoption cost: nothing
+ *
+ * The CURRENT on-disk shape *is* version 1, and an ABSENT `schemaVersion` reads
+ * as 1 — so no live instance needs rewriting and nothing pre-adoption can break,
+ * because those files genuinely are v1. Files we write carry the field
+ * explicitly; existing files gain it whenever they are next written for some
+ * other reason. There is no backfill.
+ *
+ * ## When to bump — read this before changing either format
+ *
+ * Bump ONLY when an old reader would get the wrong answer, or a new reader
+ * cannot recover the truth from an old file:
+ *
+ * | Change                                              | Bump? |
+ * | --------------------------------------------------- | ----- |
+ * | Add an optional key with a safe default             | **No** — lenient parsing already handles it |
+ * | Rename a key                                        | Yes   |
+ * | Change what an existing key *means*                 | Yes — silent misinterpretation, the dangerous one |
+ * | Change a default so *absence* now means something new | Yes |
+ * | Remove a load-bearing key                           | Yes   |
+ *
+ * Adding a key does not bump, which covers most changes. The additive-vs-
+ * breaking distinction is expressed by NOT bumping, rather than by a second
+ * version component — hence a monotonic integer and never semver. A data file
+ * has one consumer, the app, and it always wants latest: there is no version
+ * negotiation for a minor/patch to describe, and migrations chain (1→2→3), which
+ * "does 1.2→2.0 include 1.3?" cannot express. Rails, Django, SQLite's
+ * `user_version` and IndexedDB all land in the same place.
+ *
+ * Worked example, so the table is not abstract. v0.64.0's `managed` default is
+ * `managed ?? !(repo || path)` (`project-paths.ts`) — row four, the absence of a
+ * key acquiring a derived meaning. Under this scheme that was a 1→2 migration:
+ * read v1, compute `managed`, write it explicitly, stamp 2. Instead it is a
+ * derivation re-evaluated on every read, forever, with `stripDto` deliberately
+ * letting `managed` survive so the first PATCH pins it. It works, but it is a
+ * migration in disguise, and that pattern accretes.
+ *
+ * The two constants are independent on purpose: a breaking change to
+ * `project.yaml` should not force every `paddock.config.yaml` to claim a version
+ * whose shape it never had. They happen to both be 1 today.
+ */
+/** Schema version of the `project.yaml` format this build writes and understands. */
+export const PROJECT_SCHEMA_VERSION = 1;
+/** Schema version of the `paddock.config.yaml` format this build writes and understands. */
+export const CONFIG_SCHEMA_VERSION = 1;
+/** The key both formats carry it under. */
+export const SCHEMA_VERSION_KEY = "schemaVersion";
+/**
+ * The version a parsed file declares, or `null` if it declares something we
+ * cannot make sense of.
+ *
+ * - **Absent / null** → {@link PROJECT_SCHEMA_VERSION}-era, i.e. `1`. Every file
+ *   written before adoption is genuinely a v1 file.
+ * - A positive integer (or a string spelling one, since YAML quoting is easy to
+ *   get wrong by hand) → that integer.
+ * - Anything else — `0`, `-1`, `1.5`, `"banana"`, a list — → `null`.
+ *
+ * `null` is deliberately treated by callers the same way a from-the-future
+ * version is, not the same way an absent one is. A file whose own claim about
+ * its shape is unreadable is a file we cannot establish is safe to rewrite, and
+ * the failure mode this whole mechanism exists to prevent is rewriting one we
+ * did not understand.
+ */
+export function readSchemaVersion(raw) {
+    if (raw === undefined || raw === null)
+        return 1;
+    const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw.trim()) : NaN;
+    if (!Number.isInteger(n) || n < 1)
+        return null;
+    return n;
+}
+/** How a declared version reads in a message, including the unreadable case. */
+function describeDeclared(raw) {
+    const found = readSchemaVersion(raw);
+    return found === null ? `an unreadable \`schemaVersion\` (${JSON.stringify(raw)})` : `version ${found}`;
+}
+/** Whether `raw` declares a version this build cannot safely read. */
+export function isFromTheFuture(raw, supported) {
+    const found = readSchemaVersion(raw);
+    return found === null || found > supported;
+}
+/**
+ * Why `paddock.config.yaml` is unreadable by this build, or `undefined` if it is
+ * fine. Pure, so the decision is testable without a filesystem.
+ *
+ * Fail-closed, in the same shape as the `claudeHome`-points-at-your-own-`~/.claude`
+ * refusal in `config.ts`: an instance config from the future governs auth mode,
+ * bind host and data paths, and half-understanding those is worse than not
+ * starting.
+ */
+export function configSchemaRefusal(raw, configPath) {
+    if (!isFromTheFuture(raw, CONFIG_SCHEMA_VERSION))
+        return undefined;
+    return (`refusing to start: ${configPath} declares ${describeDeclared(raw)} of the paddock config ` +
+        `format, but this build understands up to version ${CONFIG_SCHEMA_VERSION}. It was written ` +
+        `by a NEWER paddock. Reading it with this build would silently drop every key this version ` +
+        `does not know, and the next write would persist the loss. Upgrade paddock to a version that ` +
+        `understands it, or point PADDOCK_CONFIG at a config file this build wrote.`);
+}
+/**
+ * Why a `project.yaml` cannot be read by this build, or `undefined` if it is fine.
+ *
+ * Asymmetric with {@link configSchemaRefusal} on purpose, and this is the
+ * judgement call worth knowing about: a project from the future is SKIPPED,
+ * loudly, rather than refusing the boot. `readSafe` already returns `null` for
+ * an unreadable `project.yaml` and the project simply vanishes from `list()`, so
+ * saying it out loud is a strict improvement on today. Bricking a whole instance
+ * because one project directory was copied in from a newer box would be a worse
+ * failure than the data loss being prevented.
+ */
+export function projectSchemaSkip(raw, file) {
+    if (!isFromTheFuture(raw, PROJECT_SCHEMA_VERSION))
+        return undefined;
+    return (`skipping a project: ${file} declares ${describeDeclared(raw)} of the paddock project ` +
+        `format, but this build understands up to version ${PROJECT_SCHEMA_VERSION}. It was written ` +
+        `by a NEWER paddock. The project is hidden — NOT deleted, and the file is left exactly as it ` +
+        `is — because reading it here would drop the keys this version does not know and the next ` +
+        `save would persist that loss. Upgrade paddock to see it again.`);
+}

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

@@ -98,6 +98,17 @@ export interface ActiveInfo {
     jobId: string | null;
     running: boolean;
 }
+/** Why a turn is being cancelled, and which socket asked for it. */
+export interface CancelIntent {
+    /**
+     * `stop` — a user pressed Stop (`chat:cancel`): they are taking control back.
+     * `quiesce` — a destructive op is stopping the turn so it can safely mutate
+     * the transcript (#731); the chat is being deleted, reverted or promoted.
+     */
+    reason: "stop" | "quiesce";
+    /** The socket that asked, if any. */
+    origin: HubSocket | null;
+}
 export declare class SessionHub {
     /** sessionId → the current (running or recently-completed) turn for that session. */
     private bySession;
@@ -109,6 +120,51 @@ export declare class SessionHub {
      * button restore (#52) and streaming indicators (#53). Set by the WS layer.
      */
     onActive: ((info: ActiveInfo) => void) | null;
+    /**
+     * Notified once per turn, when that turn stops running (#627). Set by the WS
+     * layer, which uses it to drain a queued follow-up.
+     *
+     * This exists because "after a turn" was, for a long time, spelled as a call at
+     * ONE of the eight `turn.end()` sites — the `chat:send` completion. A message
+     * queued during a slash command, a trigger/spawn turn, a scheduler wake, a
+     * background sub-agent stretch or a Stopped turn was therefore persisted and
+     * then stranded, escaping only when some LATER `chat:send` happened to flush it —
+     * arriving after a message the user typed afterwards. Every one of those paths
+     * already funnels through {@link end}, so hanging the drain here makes "drain on
+     * every turn-ending path" structural rather than a list somebody has to remember
+     * to extend — including for turn paths that don't exist yet.
+     *
+     * Fires only once a turn's session id is known (a turn that died before its id
+     * resolved has no chat to drain), and always AFTER the terminal frame its caller
+     * emitted, so a drained follow-up's bubble lands below the turn it followed.
+     */
+    onTurnEnd: ((info: {
+        sessionId: string;
+        projectSlug: string;
+        origin: HubSocket | null;
+        /** Set when this end was CAUSED by an explicit cancel — see {@link noteCancel}. */
+        cancel?: CancelIntent;
+    }) => void) | null;
+    /**
+     * Why a turn was cancelled, and by whom, pending the end it causes.
+     * Consumed by the next {@link end} for that session.
+     */
+    private cancels;
+    /**
+     * Record that a cancel was just issued for `sessionId`, so the turn end it
+     * causes can be told apart from a turn that finished on its own.
+     *
+     * The distinction is not cosmetic: "the turn ended" and "the user took control
+     * back" call for opposite treatment of anything queued behind that turn. A
+     * `stop` hands the queued message back to the client that pressed Stop; a
+     * `quiesce` (the destructive-op interlock, #731) must not touch it at all —
+     * that caller is about to delete or rewrite the transcript, and starting a
+     * fresh turn into it is the resurrection #730 was about.
+     *
+     * `origin` is the socket that asked, so the WS layer knows where to hand the
+     * message back; null when the cancel came from no socket at all.
+     */
+    noteCancel(sessionId: string, intent: CancelIntent): void;
     /**
      * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
      * chat / a slash command) so the turn is re-attachable from its very first
@@ -143,7 +199,19 @@ export declare class SessionHub {
      * like `chat:queued_flushed` that must reach a client that reconnected on a new
      * socket after the origin died.
      */
-    broadcast(sessionId: string, msg: HubMessage): void;
+    broadcast(sessionId: string, msg: HubMessage, opts?: {
+        except?: HubSocket | null;
+    }): void;
+    /**
+     * The session a cancellable job id belongs to, or null if no tracked turn
+     * carries it. `chat:cancel` names only a job id, so this is how the WS layer
+     * learns WHICH chat a Stop was aimed at. Covers a background stretch too — it
+     * publishes its synthetic id on its own hub turn (#528).
+     */
+    sessionForJob(jobId: string): {
+        sessionId: string;
+        projectSlug: string;
+    } | null;
     /** Whether a session currently has a RUNNING turn plus its job id, or null. */
     activeInfo(sessionId: string): ActiveInfo | null;
     /** Snapshot of every session with a running turn (for a newly-connected client). */

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

@@ -50,6 +50,47 @@ export class SessionHub {
      * button restore (#52) and streaming indicators (#53). Set by the WS layer.
      */
     onActive = null;
+    /**
+     * Notified once per turn, when that turn stops running (#627). Set by the WS
+     * layer, which uses it to drain a queued follow-up.
+     *
+     * This exists because "after a turn" was, for a long time, spelled as a call at
+     * ONE of the eight `turn.end()` sites — the `chat:send` completion. A message
+     * queued during a slash command, a trigger/spawn turn, a scheduler wake, a
+     * background sub-agent stretch or a Stopped turn was therefore persisted and
+     * then stranded, escaping only when some LATER `chat:send` happened to flush it —
+     * arriving after a message the user typed afterwards. Every one of those paths
+     * already funnels through {@link end}, so hanging the drain here makes "drain on
+     * every turn-ending path" structural rather than a list somebody has to remember
+     * to extend — including for turn paths that don't exist yet.
+     *
+     * Fires only once a turn's session id is known (a turn that died before its id
+     * resolved has no chat to drain), and always AFTER the terminal frame its caller
+     * emitted, so a drained follow-up's bubble lands below the turn it followed.
+     */
+    onTurnEnd = null;
+    /**
+     * Why a turn was cancelled, and by whom, pending the end it causes.
+     * Consumed by the next {@link end} for that session.
+     */
+    cancels = new Map();
+    /**
+     * Record that a cancel was just issued for `sessionId`, so the turn end it
+     * causes can be told apart from a turn that finished on its own.
+     *
+     * The distinction is not cosmetic: "the turn ended" and "the user took control
+     * back" call for opposite treatment of anything queued behind that turn. A
+     * `stop` hands the queued message back to the client that pressed Stop; a
+     * `quiesce` (the destructive-op interlock, #731) must not touch it at all —
+     * that caller is about to delete or rewrite the transcript, and starting a
+     * fresh turn into it is the resurrection #730 was about.
+     *
+     * `origin` is the socket that asked, so the WS layer knows where to hand the
+     * message back; null when the cancel came from no socket at all.
+     */
+    noteCancel(sessionId, intent) {
+        this.cancels.set(sessionId, intent);
+    }
     /**
      * Begin tracking a turn. Pass `sessionId` when it's already known (a resumed
      * chat / a slash command) so the turn is re-attachable from its very first
@@ -129,7 +170,7 @@ export class SessionHub {
      * like `chat:queued_flushed` that must reach a client that reconnected on a new
      * socket after the origin died.
      */
-    broadcast(sessionId, msg) {
+    broadcast(sessionId, msg, opts = {}) {
         const set = new Set();
         const turn = this.bySession.get(sessionId);
         if (turn?.origin)
@@ -138,9 +179,24 @@ export class SessionHub {
         if (subs)
             for (const s of subs)
                 set.add(s);
+        if (opts.except)
+            set.delete(opts.except);
         for (const s of set)
             SessionHub.write(s, msg);
     }
+    /**
+     * The session a cancellable job id belongs to, or null if no tracked turn
+     * carries it. `chat:cancel` names only a job id, so this is how the WS layer
+     * learns WHICH chat a Stop was aimed at. Covers a background stretch too — it
+     * publishes its synthetic id on its own hub turn (#528).
+     */
+    sessionForJob(jobId) {
+        for (const [sessionId, turn] of this.bySession) {
+            if (turn.jobId === jobId)
+                return { sessionId, projectSlug: turn.projectSlug };
+        }
+        return null;
+    }
     // --- internals, driven by TurnHandle -------------------------------------
     /** Whether a session currently has a RUNNING turn plus its job id, or null. */
     activeInfo(sessionId) {
@@ -191,11 +247,27 @@ export class SessionHub {
     }
     /** Mark a turn finished; retain its buffer briefly for an end-of-turn reconnect. */
     end(turn) {
+        if (!turn.running)
+            return; // already ended — never fire onTurnEnd twice
         turn.running = false;
         if (turn.sessionId) {
             this.fireActive(turn);
             turn.evictTimer = setTimeout(() => this.evict(turn), COMPLETED_TTL_MS);
             turn.evictTimer.unref?.();
+            // #627: the session is idle again — let the WS layer deal with anything
+            // queued behind this turn. Never allowed to throw into a caller finalizing
+            // its turn. A pending cancel intent belongs to THIS end, so consume it.
+            const cancel = this.cancels.get(turn.sessionId);
+            this.cancels.delete(turn.sessionId);
+            if (this.onTurnEnd) {
+                const { sessionId, projectSlug, origin } = turn;
+                try {
+                    this.onTurnEnd({ sessionId, projectSlug, origin, ...(cancel ? { cancel } : {}) });
+                }
+                catch {
+                    /* a drain that throws must not break turn teardown */
+                }
+            }
         }
     }
     /**

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

@@ -266,6 +266,31 @@ export interface TaskToolUses {
     paired: TaskToolUse[];
     /** Launches still in flight (no tool_result yet), in file order. */
     pending: TaskToolUse[];
+    /** What of this transcript belongs to a sub-agent's own lane — see {@link SidechainLines}. */
+    sidechain: SidechainLines;
+}
+/**
+ * The sub-agent-lane content of one transcript (issue #727).
+ *
+ * A sub-agent's steps belong INSIDE its Task card, served by the subagents
+ * endpoint — never as top-level rows of the parent transcript. The live path
+ * enforces that in five places via `isSidechainMessage` (`ws-turn.ts`), but the
+ * history path had no equivalent: `@herdctl/core`'s parser treats `isSidechain`
+ * as a whole-SESSION property (a sidechain gets its own file) and drops the
+ * per-line flag from the `ChatMessage` it returns, so any sidechain line written
+ * INTO a main transcript is parsed as a first-class message and served by
+ * `/messages`. This recovers the markers from the raw transcript, which is the
+ * only place they survive.
+ *
+ * Recovered in the same pass as the Task launches above, so it costs no extra I/O.
+ */
+export interface SidechainLines {
+    /** `uuid` of every sidechain line — the key `ChatMessage.uuid` joins on. */
+    uuids: Set<string>;
+    /** `tool_use.id` of every Task/Agent launched FROM a sidechain line (a sub-agent
+     *  spawning its own sub-agent). Dropped from the parent's join so the file-order
+     *  alignment survives losing the sidechain messages. */
+    taskIds: Set<string>;
 }
 /**
  * Stream the main session transcript and recover, in file order, every
@@ -277,6 +302,46 @@ export interface TaskToolUses {
  * launches separately, and mixing them here would break that alignment.
  */
 export declare function readTaskToolUses(projectDir: string, sessionId: string): Promise<TaskToolUse[]>;
+/**
+ * True when a raw transcript LINE was written on a sub-agent's own lane.
+ *
+ * Two markers, because the writers disagree: Claude Code stamps `isSidechain:
+ * true` (plus an `agentId`) on the line, while the SDK message stream — which
+ * `isSidechainMessage` in `ws-turn.ts` reads live, and which the test harness
+ * mirrors onto disk — carries `parent_tool_use_id`. Either is conclusive.
+ *
+ * Exported because EVERY file-order join over a main transcript has to agree with
+ * {@link dropSidechainMessages} about which lines exist: a scan that keeps a
+ * sidechain line while the parsed message list has dropped it shifts the whole
+ * join by one (#727).
+ */
+export declare function isSidechainLine(parsed: {
+    isSidechain?: unknown;
+    parent_tool_use_id?: unknown;
+    message?: {
+        parent_tool_use_id?: unknown;
+    };
+}): boolean;
+/**
+ * Drop a session's sub-agent sidechain steps from its parsed history (issue
+ * #727) — the history-path counterpart of the live path's `isSidechainMessage`
+ * filter, and the same invariant: a sub-agent's steps render INSIDE its Task
+ * card (via the subagents endpoint), never as top-level rows of the parent.
+ *
+ * Joins on `uuid`, the source line's own id, which `@herdctl/core` preserves on
+ * every parsed message (and, for a paired tool message, takes from the
+ * originating `tool_use` entry — so a sidechain tool call matches on the same
+ * line that made it sidechain). Rides the mtime-cached transcript scan, and
+ * short-circuits to the identity for the overwhelmingly common transcript with
+ * no sidechain lines at all, so this costs nothing on the normal path.
+ *
+ * A transcript that is sidechain top to bottom is not a parent with leaked steps
+ * — it IS a sub-agent's own session, the shape Claude Code writes as its own
+ * `agent-<hex>.jsonl`. herdctl keeps those out of session discovery, but if one
+ * is ever reached directly it should render its content, not an empty chat, so
+ * a drop that would empty the history is refused.
+ */
+export declare function dropSidechainMessages<T extends ChatMessage>(projectDir: string, sessionId: string, messages: T[]): Promise<T[]>;
 /**
  * Live sub-agent enrichment for a tool frame (issue #429). When the tool is a
  * `Task`/`Agent` launch this turn already recovered (via {@link extractSubagentLaunches}),