@edspencer/paddock 0.65.0 → 0.66.0

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

@@ -24,6 +24,7 @@ import { childOf, HUMAN_ROOT, ADOPTED_ROOT } from "../run-provenance.js";
 import { sendProjectError } from "../route-errors.js";
 import { mapWithConcurrency, FILE_FANOUT_CONCURRENCY } from "../concurrency.js";
 import { CHAT_USAGE_SCOPES, SAFE_SESSION_ID, RUNS_SEEN_SESSION, clampRunsLimit, toChatUsage, buildProjectChats, makeTriggerResolver, makeParentResolver, normalizeBatchSessionIds, BATCH_SESSIONS_MAX, } from "../chat-dto.js";
+import { quiesceSession, turnRunningError } from "../turn-interlock.js";
 /**
  * Workspace-scoped chat routes: paths are declared RELATIVE to the workspace
  * (e.g. `/chats/:sessionId`), and this plugin is mounted TWICE — once at
@@ -56,6 +57,17 @@ export function registerChatWorkspaceRoutes(app, ctx) {
      * feed then degrades to its unread half instead of 500ing.
      */
     const isRunning = (sessionId) => ctx.managementOpsContext?.hub.isRunning(sessionId) ?? false;
+    /**
+     * The interlock every DESTRUCTIVE chat route runs first (issue #731).
+     *
+     * `claude` writes the transcript itself, so unlinking or rewriting it while a
+     * turn is live does not remove the chat — the surviving process re-creates the
+     * file from its own tail and the chat comes back with its history gone. These
+     * routes therefore stop the turn and WAIT for it to be dead before touching a
+     * byte; `stuck` means we could not confirm that, and the only safe answer then
+     * is to refuse.
+     */
+    const interlock = { hub: ctx.managementOpsContext?.hub, herdctl };
     // --- chats (sessions) --------------------------------------------------
     app.get("/chats", {
         schema: {
@@ -595,7 +607,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object `{ ok, removed }` indicating whether the transcript was removed.",
+                    description: "Object `{ ok, removed, retained, cancelledTurn }` — whether the transcript was removed, and whether a live turn had to be stopped first (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped, so nothing was deleted (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -604,6 +621,15 @@ export function registerChatWorkspaceRoutes(app, ctx) {
     }, async (req, reply) => {
         try {
             const agent = await agentForSlug(req.params.slug);
+            // #731: stop any in-flight turn FIRST. A delete is an unambiguous "this
+            // chat is going away", so we cancel rather than refuse — refusing would
+            // strand the user behind a turn that may never end (a hung turn was
+            // exactly how this was found). If the turn will not die we refuse, since
+            // deleting under a live writer is what resurrected the chat.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             await cleanupAttachments(agent, req.params.sessionId);
             const { removed, retained } = await herdctl.deleteSession(agent, req.params.sessionId);
             // Drop any archived/starred/unread/detached flag so a future session id
@@ -619,7 +645,9 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             // has to be cleared on the same path — otherwise a recycled session id
             // silently starts life detached from a parent it never had.
             await parentDetach.setDetached(agent, req.params.sessionId, false).catch(() => undefined);
-            return reply.code(200).send({ ok: true, removed, retained });
+            return reply
+                .code(200)
+                .send({ ok: true, removed, retained, cancelledTurn: quiesced === "stopped" });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -751,7 +779,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 200: {
-                    description: "Object reporting how many messages were removed.",
+                    description: "Object reporting how many messages were removed, and whether a live turn had to be stopped first (`cancelledTurn`, #731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped, so nothing was truncated (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -763,8 +796,19 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             if (!uuid)
                 return reply.code(400).send({ error: "uuid is required" });
             const project = await projects.get(req.params.slug);
+            // #731: revert truncates the LIVE transcript in place — the same file a
+            // running turn is appending to — so mid-turn it left an orphan
+            // `tool_result` whose `tool_use` had just been truncated away. Cancel
+            // rather than refuse: an in-flight turn is by definition part of the tail
+            // the user just asked to throw away.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             const { removed } = await herdctl.revertSession(project, req.params.sessionId, uuid);
-            return reply.code(200).send({ ok: true, removed });
+            return reply
+                .code(200)
+                .send({ ok: true, removed, cancelledTurn: quiesced === "stopped" });
         }
         catch (err) {
             return sendProjectError(reply, err);
@@ -1206,6 +1250,14 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             const failed = [];
             for (const sessionId of sessionIds) {
                 try {
+                    // #731: same interlock as the single delete, per id. A chat whose
+                    // turn refuses to die lands in `failed` rather than aborting the
+                    // batch — the route is already best-effort-and-honest per chat, and
+                    // "still running" is exactly the kind of partial failure it reports.
+                    if ((await quiesceSession(interlock, sessionId)) === "stuck") {
+                        failed.push(sessionId);
+                        continue;
+                    }
                     await cleanupAttachments(agent, sessionId);
                     const gone = await herdctl.deleteSession(agent, sessionId);
                     // `retained` counts as success here, and the distinction matters for
@@ -1279,7 +1331,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             },
             response: {
                 201: {
-                    description: "Object `{ project, promoted, sessionId }` describing the created project and whether the transcript was re-homed.",
+                    description: "Object `{ project, promoted, sessionId, cancelledTurn }` describing the created project, whether the transcript was re-homed, and whether a live turn had to be stopped first (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
+                409: {
+                    description: "`{ code: 'turn_running' }` — a turn is still running on this chat and could not be stopped. Nothing was moved and NO project was created (#731).",
                     type: "object",
                     additionalProperties: true,
                 },
@@ -1292,6 +1349,15 @@ export function registerChatWorkspaceRoutes(app, ctx) {
         }
         try {
             const from = await projects.get(req.params.slug);
+            // #731: promote MOVES the transcript, so mid-turn it lost the chat from
+            // BOTH projects — the surviving process rewrote the source path it still
+            // held, while the moved copy went unlisted in the target with no recovery
+            // path in the UI. Quiesce BEFORE `projects.create` so a refusal doesn't
+            // leave an empty project behind as a side-effect of a failed promote.
+            const quiesced = await quiesceSession(interlock, req.params.sessionId);
+            if (quiesced === "stuck") {
+                return reply.code(409).send(turnRunningError([req.params.sessionId]));
+            }
             const project = await projects.create({
                 name: body.name,
                 slug: body.slug,
@@ -1315,7 +1381,12 @@ export function registerChatWorkspaceRoutes(app, ctx) {
             catch (err) {
                 req.log.warn({ err }, "promote: could not re-home the transcript");
             }
-            return reply.code(201).send({ project, promoted, sessionId: req.params.sessionId });
+            return reply.code(201).send({
+                project,
+                promoted,
+                sessionId: req.params.sessionId,
+                cancelledTurn: quiesced === "stopped",
+            });
         }
         catch (err) {
             return sendProjectError(reply, err);

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

@@ -1,9 +1,10 @@
-import { ProjectError, ROOT_KEY, } from "../projects.js";
+import { ProjectError, ROOT_KEY, isRootKey, } from "../projects.js";
 import { keeperAgentName } from "../herdctl.js";
 import { isKnownModel, isKnownPermissionMode, isValidMaxTurns, isKnownDriveMode, resolveModels, MAX_TURNS_LIMIT, } from "../models.js";
 import { isValidMaxSpawnDepth, MAX_SPAWN_DEPTH_LIMIT } from "../spawn-capability.js";
 import { sendProjectError } from "../route-errors.js";
 import { buildProjectChats, makeTriggerResolver, makeParentResolver } from "../chat-dto.js";
+import { quiesceProject, turnRunningError } from "../turn-interlock.js";
 /**
  * Build ONE workspace's compact `{ sessionId, lastTurnCompletedAt, lastSeen?,
  * unread? }` list — the sidebar's UNREAD-badge feed (#161), server-backed (#189).
@@ -406,11 +407,30 @@ export function registerProjectWorkspaceRoutes(app, ctx) {
                     type: "object",
                     additionalProperties: true,
                 },
+                409: {
+                    description: "`{ code: 'turn_running', sessionIds }` — one or more of the project's chats has a turn that could not be stopped, so nothing was deleted (#731).",
+                    type: "object",
+                    additionalProperties: true,
+                },
             },
         },
     }, async (req, reply) => {
         try {
-            const project = await projects.remove(req.params.slug); // throws not_found
+            // #731: a project delete takes every chat in it, so it races the same live
+            // writers a chat delete does — and the orphaned `claude` was observed
+            // running on with a cwd of `…/<slug> (deleted)`. Stop them all first, and
+            // refuse rather than remove the directory out from under one.
+            //
+            // `remove()` refuses the ROOT workspace, and a refusal must not have killed
+            // the root's live turns on the way to saying no — so that one check comes
+            // first, mirroring the guard in `remove()` rather than duplicating its
+            // error.
+            if (!isRootKey(req.params.slug)) {
+                const stuck = await quiesceProject({ hub: ctx.managementOpsContext?.hub, herdctl }, req.params.slug);
+                if (stuck.length > 0)
+                    return reply.code(409).send(turnRunningError(stuck));
+            }
+            const project = await projects.remove(req.params.slug); // throws not_found / refuses root
             try {
                 await herdctl.removeProjectAgent(project.slug, Object.keys(project.hooks ?? {}), Object.keys(project.triggers ?? {}));
             }

package/packages/server/dist/schema-version.d.ts

@@ -0,0 +1,111 @@
+/**
+ * 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 declare const PROJECT_SCHEMA_VERSION = 1;
+/** Schema version of the `paddock.config.yaml` format this build writes and understands. */
+export declare const CONFIG_SCHEMA_VERSION = 1;
+/** The key both formats carry it under. */
+export declare 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 declare function readSchemaVersion(raw: unknown): number | null;
+/** Whether `raw` declares a version this build cannot safely read. */
+export declare function isFromTheFuture(raw: unknown, supported: number): boolean;
+/**
+ * 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 declare function configSchemaRefusal(raw: unknown, configPath: string): string | undefined;
+/**
+ * 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 declare function projectSchemaSkip(raw: unknown, file: string): string | undefined;

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/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}),