@edspencer/paddock 0.64.0 → 0.66.0

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

@@ -96,7 +96,7 @@ export const FORK_CHAT_BATCH_DESC = "FAN-OUT primitive: fork ONE source chat int
     `"<name_prefix> <i>" (1-based). With \`model\`, every fork's kickoff turn runs on ` +
     `that model. Up to ${FORK_BATCH_MAX} forks per call; they run ` +
     "concurrently. Returns the source and every new child's sessionId.";
-// ── Project tools (issue #467) ──────────────────────────────────────────────
+// ── Project tools (issues #467, #470) ───────────────────────────────────────
 export const CREATE_PROJECT_DESC = "Create a BRAND-NEW Paddock project — the workspace a keeper agent lives in — and " +
     "register its keeper. `name` is the only required argument; the kebab-case `slug` " +
     "is derived from it unless you pass one. Two kinds: pass a `repo` git URL for a " +
@@ -109,6 +109,19 @@ export const CREATE_PROJECT_DESC = "Create a BRAND-NEW Paddock project — the w
     "pass that slug to `create_chat` to start working in it. A bad or unreachable " +
     "repo URL fails cleanly and leaves NO half-created project behind, so it is safe " +
     "to retry with a corrected URL.";
+export const PROMOTE_PROJECT_DESC = "Turn an EXISTING notebook project into a REPO-BACKED one, in place — use this " +
+    "when a notes-only project has grown into (or was always meant to be) a codebase, " +
+    "instead of creating a second project and abandoning the first. `repo` (a git URL) " +
+    "is required; `project` defaults to the CURRENT project, so an agent can promote " +
+    "the workspace it is running in. The repo is cloned into a nested checkout inside " +
+    "the project, that checkout becomes the agent's working directory, and the agent is " +
+    "re-registered there. Everything already in the project is KEPT — its existing " +
+    "chats stay listed and resumable, and its OVERVIEW/CHANGELOG/settings are " +
+    "untouched. Not reversible through this MCP, and only ever notebook → repo-backed: " +
+    "a project that is ALREADY repo-backed is refused, as is the root workspace. A bad " +
+    "or unreachable repo URL fails cleanly, leaving the notebook exactly as it was, so " +
+    "it is safe to retry with a corrected URL. Returns the project's new working " +
+    "directory and whether its agent re-registered.";
 // ── Unified trigger tools (Epic T / T3) ─────────────────────────────────────
 export const SET_TRIGGER_DESC = "Create or update a unified project TRIGGER — a standing rule that runs an agent " +
     "turn when something happens, keyed by `name`. Enable/disable is just this call " +

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

@@ -54,6 +54,13 @@ export interface SelfMcpCreatedProject {
      */
     agentRegistered: boolean;
 }
+/**
+ * A promoted project as surfaced back to the agent (issue #470). Declared as an
+ * ALIAS rather than a second copy of the same fields: promotion's whole point is
+ * that the project ends up in exactly the state a repo-backed `create_project`
+ * would have produced, so the two reports must not be able to drift.
+ */
+export type SelfMcpPromotedProject = SelfMcpCreatedProject;
 /** A chat as surfaced to the agent. */
 export interface SelfMcpChat {
     /** Owning project slug. */
@@ -192,10 +199,11 @@ export interface SelfMcpWriteContext {
     /** Set (or clear) a chat's archived flag (presentational metadata only). */
     setArchived: (projectSlug: string, sessionId: string, archived: boolean) => Promise<void>;
     /**
-     * Whether the PROJECT tools (`create_project`, issue #467) are enabled for this
-     * instance — the `selfMcpProjectsEnabled` gate, resolved by the caller. When false
-     * the tool is NOT injected at all (absent, not present-but-refusing), the same
-     * binary discipline as {@link triggersMcpEnabled}.
+     * Whether the PROJECT tools (`create_project`, issue #467; `promote_project`,
+     * issue #470) are enabled for this instance — the `selfMcpProjectsEnabled` gate,
+     * resolved by the caller. When false the tools are NOT injected at all (absent,
+     * not present-but-refusing), the same binary discipline as
+     * {@link triggersMcpEnabled}.
      */
     projectsMcpEnabled: boolean;
     /**
@@ -208,6 +216,20 @@ export interface SelfMcpWriteContext {
      * non-fatal (mirroring the route) and reported via `agentRegistered`.
      */
     createProject: (input: SelfMcpCreateProjectInput) => Promise<SelfMcpCreatedProject>;
+    /**
+     * Promote an EXISTING notebook project to repo-backed in place, and re-register
+     * its agent — the SAME two steps `POST /api/projects/:slug/promote` performs, in
+     * the same order (`ProjectStore.promote` then `ensureProjectAgent`), so the REST
+     * and MCP paths cannot drift (issue #470/#213). All the real work (the already-
+     * repo-backed / root-workspace / bad-URL guards, the clone into the nested
+     * checkout, the `writeYaml` commit point and its rollback to an UNTOUCHED
+     * notebook on failure) stays in the store. Throws on a promote failure; a
+     * re-registration failure is non-fatal (mirroring the route) and reported via
+     * `agentRegistered` — though it matters more here than for create, since
+     * re-registration is what re-symlinks the new working dir at the project's
+     * existing `.chats/` store so its chats stay listed and resumable.
+     */
+    promoteProject: (projectSlug: string, repo: string) => Promise<SelfMcpPromotedProject>;
     /**
      * Whether the unified trigger-management MCP is enabled for THIS turn's project
      * (Epic T / T3 — the successor to the G5 hook-MCP gate, resolved from the SAME

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

@@ -32,4 +32,25 @@ export declare function archiveChatHandler(write: SelfMcpWriteContext, archived:
  * an unclonable repo, and still rolls the whole project dir back on a clone failure.
  */
 export declare function createProjectHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
+/**
+ * `promote_project` (issue #470) — turn an EXISTING notebook project into a
+ * repo-backed one in place, over the same `ProjectStore.promote` (#213) that
+ * `POST /api/projects/:slug/promote` uses. Shares `create_project`'s
+ * `projectsMcpEnabled` gate: same blast-radius class (it clones a caller-supplied
+ * URL and restructures a project), and this one MUTATES existing state.
+ *
+ * Pure, like its siblings: it resolves the target (defaulting to the current
+ * project, as every other project-targeting write tool does), shape-checks the URL
+ * with the very same `isValidRepoUrl` the store uses, and delegates. Everything
+ * that makes promotion safe — the already-repo-backed / root-workspace / existing-
+ * checkout-dir guards, and the rollback that leaves an untouched notebook when the
+ * clone fails — stays in the store; nothing is re-implemented here.
+ *
+ * Deliberately NO up-front `SLUG_RE` check on the target, unlike `create_project`:
+ * there the slug names a project being INVENTED, here it names one that must
+ * already exist, so the store's own `not_found` is both the real check and the
+ * better message — and `SLUG_RE` would reject the root workspace's legitimate ""
+ * key with a misleading "invalid slug" instead of the store's explicit refusal.
+ */
+export declare function promoteProjectHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;
 export declare function forkChatBatchHandler(write: SelfMcpWriteContext): (args: Record<string, unknown>) => Promise<McpToolCallResult>;

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

@@ -171,6 +171,50 @@ export function createProjectHandler(write) {
         }
     };
 }
+/**
+ * `promote_project` (issue #470) — turn an EXISTING notebook project into a
+ * repo-backed one in place, over the same `ProjectStore.promote` (#213) that
+ * `POST /api/projects/:slug/promote` uses. Shares `create_project`'s
+ * `projectsMcpEnabled` gate: same blast-radius class (it clones a caller-supplied
+ * URL and restructures a project), and this one MUTATES existing state.
+ *
+ * Pure, like its siblings: it resolves the target (defaulting to the current
+ * project, as every other project-targeting write tool does), shape-checks the URL
+ * with the very same `isValidRepoUrl` the store uses, and delegates. Everything
+ * that makes promotion safe — the already-repo-backed / root-workspace / existing-
+ * checkout-dir guards, and the rollback that leaves an untouched notebook when the
+ * clone fails — stays in the store; nothing is re-implemented here.
+ *
+ * Deliberately NO up-front `SLUG_RE` check on the target, unlike `create_project`:
+ * there the slug names a project being INVENTED, here it names one that must
+ * already exist, so the store's own `not_found` is both the real check and the
+ * better message — and `SLUG_RE` would reject the root workspace's legitimate ""
+ * key with a misleading "invalid slug" instead of the store's explicit refusal.
+ */
+export function promoteProjectHandler(write) {
+    return async (args) => {
+        try {
+            const projectArg = typeof args.project === "string" ? args.project.trim() : "";
+            const projectSlug = projectArg.length > 0 ? projectArg : write.currentProjectSlug;
+            const repo = typeof args.repo === "string" ? args.repo.trim() : "";
+            if (!repo) {
+                return fail("Error: `repo` is required (the git URL to back the project with).");
+            }
+            if (!isValidRepoUrl(repo)) {
+                return fail(`Error: invalid repo URL "${repo}" — expected an https://, git://, ssh:// or ` +
+                    "git@host:owner/repo url.");
+            }
+            const project = await write.promoteProject(projectSlug, repo);
+            return ok({ promoted: true, ...project });
+        }
+        catch (error) {
+            // Same hygiene as create_project: a clone failure arrives as git's whole argv
+            // (`Command failed: git clone -- <url> <dest>`), and the agent needs the repo
+            // URL + git's reason, not our on-disk layout.
+            return fail(`Error promoting project: ${truncateText(redactPaths(errText(error)))}`);
+        }
+    };
+}
 export function forkChatBatchHandler(write) {
     return async (args) => {
         try {

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

@@ -12,7 +12,7 @@
  *   - `self-mcp-util.ts`         — result envelopes, clamps, arg coercion + caps
  *   - `self-mcp-descriptions.ts` — the agent-facing `*_DESC` prose
  *   - `self-mcp-read.ts`         — list_projects / list_chats / read_chat handlers
- *   - `self-mcp-write.ts`        — create/fork/send/archive/fork-batch + create_project handlers
+ *   - `self-mcp-write.ts`        — create/fork/send/archive/fork-batch + project handlers
  *   - `self-mcp-triggers.ts`     — list/set/remove/run trigger handlers
  *
  * ── How it reaches the keeper ───────────────────────────────────────────────
@@ -32,7 +32,7 @@
  */
 import type { InjectedMcpServerDef } from "@herdctl/core";
 import type { SelfMcpContext, SelfMcpWriteContext } from "./self-mcp-types.js";
-export type { SelfMcpProject, SelfMcpChat, SelfMcpMessage, SelfMcpTrigger, SelfMcpContext, SelfMcpWriteContext, SelfMcpCreateProjectInput, SelfMcpCreatedProject, } from "./self-mcp-types.js";
+export type { SelfMcpProject, SelfMcpChat, SelfMcpMessage, SelfMcpTrigger, SelfMcpContext, SelfMcpWriteContext, SelfMcpCreateProjectInput, SelfMcpCreatedProject, SelfMcpPromotedProject, } from "./self-mcp-types.js";
 export { FORK_BATCH_MAX, redactPaths, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, READ_CHAT_MAX_TEXT, clampLimit, truncateText, resolveModelArg, coercePrompts, coerceToolList, coerceBoolean, } from "./self-mcp-util.js";
 /** Assembly-time options for {@link selfMcpServerDef}. */
 export interface SelfMcpServerDefOptions {
@@ -50,8 +50,8 @@ export interface SelfMcpServerDefOptions {
  * write flag is on), the WRITE tools (create_chat/fork_chat/send_message/
  * archive_chat/unarchive_chat/fork_chat_batch) are appended too; omit it for
  * unchanged read-only behavior. Two further blocks hang off independent gates ON
- * that write context: {@link SelfMcpWriteContext.projectsMcpEnabled} (issue #467)
- * appends the project tool (create_project), and
+ * that write context: {@link SelfMcpWriteContext.projectsMcpEnabled} (issues #467,
+ * #470) appends the project tools (create_project/promote_project), and
  * {@link SelfMcpWriteContext.triggersMcpEnabled} (the per-project trigger-MCP
  * opt-in, Epic T / T3) appends the unified trigger-management tools (list_triggers/
  * set_trigger/remove_trigger/run_trigger). Inject under
@@ -75,11 +75,12 @@ export declare const SELF_MCP_WRITE_TOOL_NAMES: {
     readonly forkChatBatch: "mcp__paddock_manage__fork_chat_batch";
 };
 /**
- * The fully-qualified name of the PROJECT tool (issue #467), present only when a
- * write context has {@link SelfMcpWriteContext.projectsMcpEnabled} on.
+ * The fully-qualified names of the PROJECT tools (issues #467, #470), present only
+ * when a write context has {@link SelfMcpWriteContext.projectsMcpEnabled} on.
  */
 export declare const SELF_MCP_PROJECT_TOOL_NAMES: {
     readonly createProject: "mcp__paddock_manage__create_project";
+    readonly promoteProject: "mcp__paddock_manage__promote_project";
 };
 /**
  * The fully-qualified names of the Epic T / T3 unified trigger-management tools

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

@@ -1,7 +1,7 @@
 import { FORK_BATCH_MAX, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, } from "./self-mcp-util.js";
-import { MODEL_ARG_DESC, LIST_PROJECTS_DESC, LIST_CHATS_DESC, READ_CHAT_DESC, CREATE_CHAT_DESC, FORK_CHAT_DESC, SEND_MESSAGE_DESC, ARCHIVE_CHAT_DESC, UNARCHIVE_CHAT_DESC, FORK_CHAT_BATCH_DESC, CREATE_PROJECT_DESC, SET_TRIGGER_DESC, REMOVE_TRIGGER_DESC, RUN_TRIGGER_DESC, LIST_TRIGGERS_DESC, } from "./self-mcp-descriptions.js";
+import { MODEL_ARG_DESC, LIST_PROJECTS_DESC, LIST_CHATS_DESC, READ_CHAT_DESC, CREATE_CHAT_DESC, FORK_CHAT_DESC, SEND_MESSAGE_DESC, ARCHIVE_CHAT_DESC, UNARCHIVE_CHAT_DESC, FORK_CHAT_BATCH_DESC, CREATE_PROJECT_DESC, PROMOTE_PROJECT_DESC, SET_TRIGGER_DESC, REMOVE_TRIGGER_DESC, RUN_TRIGGER_DESC, LIST_TRIGGERS_DESC, } from "./self-mcp-descriptions.js";
 import { listProjectsHandler, listChatsHandler, readChatHandler } from "./self-mcp-read.js";
-import { createChatHandler, forkChatHandler, sendMessageHandler, archiveChatHandler, forkChatBatchHandler, createProjectHandler, } from "./self-mcp-write.js";
+import { createChatHandler, forkChatHandler, sendMessageHandler, archiveChatHandler, forkChatBatchHandler, createProjectHandler, promoteProjectHandler, } from "./self-mcp-write.js";
 import { PROJECT_STATUSES } from "./project-types.js";
 import { listTriggersHandler, setTriggerHandler, removeTriggerHandler, runTriggerHandler, } from "./self-mcp-triggers.js";
 export { FORK_BATCH_MAX, redactPaths, READ_CHAT_DEFAULT_LIMIT, READ_CHAT_MAX_LIMIT, READ_CHAT_MAX_TEXT, clampLimit, truncateText, resolveModelArg, coercePrompts, coerceToolList, coerceBoolean, } from "./self-mcp-util.js";
@@ -204,11 +204,15 @@ function writeTools(write) {
     ];
 }
 /**
- * The PROJECT tools (issue #467 — `create_project`). Appended only when
+ * The PROJECT tools (issue #467 — `create_project`; issue #470 —
+ * `promote_project`). Appended only when
  * {@link SelfMcpWriteContext.projectsMcpEnabled} is on: the same coarse binary gate
- * as the trigger tools (when off the tool is ABSENT, not present-but-refusing). Its
- * own flag because — unlike every other write tool — this one provisions
- * instance-level state and clones a caller-supplied git URL.
+ * as the trigger tools (when off the tools are ABSENT, not present-but-refusing).
+ * Their own flag because — unlike every other write tool — these provision or
+ * restructure instance-level state and clone a caller-supplied git URL. Promotion
+ * shares the flag rather than getting a third one: it is the same blast-radius
+ * class, and an operator who has granted "this agent may provision projects" has
+ * already made the decision promotion asks for.
  */
 function projectTools(write) {
     return [
@@ -244,6 +248,27 @@ function projectTools(write) {
             },
             handler: createProjectHandler(write),
         },
+        {
+            name: "promote_project",
+            description: PROMOTE_PROJECT_DESC,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    project: {
+                        type: "string",
+                        description: "Slug of the NOTEBOOK project to promote. Omit to promote the current project.",
+                    },
+                    repo: {
+                        type: "string",
+                        description: "Git URL to back the project with (https://, git://, ssh:// or " +
+                            "git@host:owner/repo). Cloned into a nested checkout that becomes the " +
+                            "agent's working directory. Required.",
+                    },
+                },
+                required: ["repo"],
+            },
+            handler: promoteProjectHandler(write),
+        },
     ];
 }
 /**
@@ -386,8 +411,8 @@ function triggerTools(write) {
  * write flag is on), the WRITE tools (create_chat/fork_chat/send_message/
  * archive_chat/unarchive_chat/fork_chat_batch) are appended too; omit it for
  * unchanged read-only behavior. Two further blocks hang off independent gates ON
- * that write context: {@link SelfMcpWriteContext.projectsMcpEnabled} (issue #467)
- * appends the project tool (create_project), and
+ * that write context: {@link SelfMcpWriteContext.projectsMcpEnabled} (issues #467,
+ * #470) appends the project tools (create_project/promote_project), and
  * {@link SelfMcpWriteContext.triggersMcpEnabled} (the per-project trigger-MCP
  * opt-in, Epic T / T3) appends the unified trigger-management tools (list_triggers/
  * set_trigger/remove_trigger/run_trigger). Inject under
@@ -428,11 +453,12 @@ export const SELF_MCP_WRITE_TOOL_NAMES = {
     forkChatBatch: `mcp__${SERVER_NAME}__fork_chat_batch`,
 };
 /**
- * The fully-qualified name of the PROJECT tool (issue #467), present only when a
- * write context has {@link SelfMcpWriteContext.projectsMcpEnabled} on.
+ * The fully-qualified names of the PROJECT tools (issues #467, #470), present only
+ * when a write context has {@link SelfMcpWriteContext.projectsMcpEnabled} on.
  */
 export const SELF_MCP_PROJECT_TOOL_NAMES = {
     createProject: `mcp__${SERVER_NAME}__create_project`,
+    promoteProject: `mcp__${SERVER_NAME}__promote_project`,
 };
 /**
  * The fully-qualified names of the Epic T / T3 unified trigger-management tools

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

package/packages/server/dist/subagents.js

@@ -88,7 +88,7 @@ export const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
  */
 export const MTIME_CACHE_MAX = 1024;
 const taskUsesCache = new Map();
-const durationCache = new Map();
+const factsCache = new Map();
 const usageCache = new Map();
 /** The file's mtime in epoch ms, or undefined if it can't be stat'd. */
 export async function statMtimeMs(file) {
@@ -137,7 +137,7 @@ export async function readTaskToolUses(projectDir, sessionId) {
  */
 async function readTaskUsesForSession(projectDir, sessionId) {
     if (!SAFE_SEGMENT.test(sessionId))
-        return { paired: [], pending: [] };
+        return emptyTaskToolUses();
     return readTaskUsesFromFile(path.join(projectChatsDir(projectDir), `${sessionId}.jsonl`));
 }
 /**
@@ -158,10 +158,32 @@ async function readTaskUsesFromFile(file) {
         mtimeCacheSet(taskUsesCache, file, mtimeMs, value);
     return value;
 }
+function emptyTaskToolUses() {
+    return { paired: [], pending: [], sidechain: { uuids: new Set(), taskIds: new Set() } };
+}
+/**
+ * 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 function isSidechainLine(parsed) {
+    if (parsed.isSidechain === true)
+        return true;
+    return Boolean(parsed.parent_tool_use_id ?? parsed.message?.parent_tool_use_id);
+}
 async function readTaskUsesFromFileUncached(file) {
     const byId = new Map();
     const order = [];
     const resultIds = new Set();
+    const sidechain = { uuids: new Set(), taskIds: new Set() };
     const stream = createReadStream(file, { encoding: "utf8" });
     stream.on("error", () => undefined);
     const rl = createInterface({ input: stream, crlfDelay: Infinity });
@@ -177,12 +199,20 @@ async function readTaskUsesFromFileUncached(file) {
             catch {
                 continue;
             }
+            // A sub-agent's OWN transcript is sidechain top to bottom, so this only ever
+            // marks anything on a MAIN session file — which is the only place the
+            // distinction means something (issue #727).
+            const onSidechain = isSidechainLine(parsed);
+            if (onSidechain && typeof parsed.uuid === "string")
+                sidechain.uuids.add(parsed.uuid);
             const content = parsed.message?.content;
             if (!Array.isArray(content))
                 continue;
             for (const block of content) {
                 const b = block;
                 if (b?.type === "tool_use" && b.name && SUBAGENT_TOOL_NAMES.has(b.name) && b.id) {
+                    if (onSidechain)
+                        sidechain.taskIds.add(b.id);
                     if (!byId.has(b.id)) {
                         order.push(b.id);
                         byId.set(b.id, {
@@ -200,7 +230,7 @@ async function readTaskUsesFromFileUncached(file) {
         }
     }
     catch {
-        return { paired: [], pending: [] };
+        return emptyTaskToolUses();
     }
     finally {
         rl.close();
@@ -209,8 +239,43 @@ async function readTaskUsesFromFileUncached(file) {
     return {
         paired: order.filter((id) => resultIds.has(id)).map((id) => byId.get(id)),
         pending: order.filter((id) => !resultIds.has(id)).map((id) => byId.get(id)),
+        sidechain,
     };
 }
+/**
+ * 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 async function dropSidechainMessages(projectDir, sessionId, messages) {
+    const { sidechain } = await readTaskUsesForSession(projectDir, sessionId);
+    if (sidechain.uuids.size === 0)
+        return messages;
+    const kept = messages.filter((m) => !(m.uuid && sidechain.uuids.has(m.uuid)));
+    return kept.length === 0 ? messages : kept;
+}
+/** The same launches minus any a sub-agent made on its own sidechain lane. */
+function withoutSidechainLaunches(uses) {
+    const { taskIds } = uses.sidechain;
+    if (taskIds.size === 0)
+        return uses;
+    const keep = (u) => !taskIds.has(u.toolUseId);
+    return { ...uses, paired: uses.paired.filter(keep), pending: uses.pending.filter(keep) };
+}
 /**
  * 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}),
@@ -306,10 +371,16 @@ export async function readSubagentMessages(projectDir, sessionId, toolUseId) {
 export async function enrichWithSubagents(projectDir, sessionId, messages) {
     if (!hasSubagentTool(messages))
         return messages;
-    const [taskUses, subagents] = await Promise.all([
+    const [rawTaskUses, subagents] = await Promise.all([
         readTaskUsesForSession(projectDir, sessionId),
         listSubagents(projectDir, sessionId),
     ]);
+    // The join is by FILE ORDER, so it has to see the same launches the caller's
+    // message list does. {@link dropSidechainMessages} has already removed the
+    // sidechain rows from that list, so a nested launch a sub-agent made on its own
+    // lane must come out of the cursor too — leaving it in would shift every
+    // following top-level sub-agent's enrichment onto the wrong card (#727).
+    const taskUses = withoutSidechainLaunches(rawTaskUses);
     const [durations, costs] = await Promise.all([
         subagentDurations(subagents),
         subagentCosts(subagents),
@@ -317,42 +388,85 @@ export async function enrichWithSubagents(projectDir, sessionId, messages) {
     return attachSubagentFields(messages, taskUses, subagents, durations, costs);
 }
 /**
- * Compute each sub-agent's run time (ms) from the first→last timestamp in its
- * own transcript. Keyed by toolUseId. Runs once per session on chat open (only
- * over that session's sub-agent files), so the cost is bounded to the open chat.
+ * How long a sub-agent transcript with no terminal `end_turn` may stay quiet
+ * before we stop calling it live (issue #725).
+ *
+ * A sub-agent that was interrupted — its keeper killed, the box restarted — never
+ * writes an `end_turn`, so without this fallback its card would advertise "still
+ * running" forever and its duration would never appear. The window has to be
+ * comfortably longer than the longest gap a WORKING sub-agent can leave between
+ * transcript lines, which is one slow tool call (a full test suite, a long build),
+ * not one slow model response. Ten minutes clears that with room to spare, and the
+ * `end_turn` check below means the overwhelming majority of finished sub-agents
+ * (392 of the 483 real transcripts this was measured against) never wait for it at
+ * all — they are recognised as finished the instant their last line lands.
+ */
+const SUBAGENT_STALE_MS = 10 * 60_000;
+/**
+ * Compute each FINISHED sub-agent's run time (ms) from the first→last timestamp
+ * in its own transcript. Keyed by toolUseId. Runs once per session on chat open
+ * (only over that session's sub-agent files), so the cost is bounded to the open
+ * chat.
+ *
+ * A sub-agent that still looks live is deliberately left OUT of the map (issue
+ * #725). `subagentDurationMs` is not merely cosmetic — it is the client's
+ * finished signal (`useRunningSubagents` drops any card that carries one) — and
+ * it is derived from a transcript that is still growing, so publishing it for a
+ * running sub-agent both freezes a bogus part-way number onto the card and
+ * evicts it from the running-sub-agents bar for the rest of the run. #622 fixed
+ * that for the `pending` branch of {@link attachSubagentFields} by omitting the
+ * field; the `paired` branch below it kept stamping one, and because the SDK
+ * backgrounds sub-agents, the launching `Task` pairs within milliseconds while
+ * the sub-agent keeps working — so a live sub-agent reaches the paired branch as
+ * a matter of course. Gating at the source fixes both branches by construction.
  */
 async function subagentDurations(subagents) {
     const out = new Map();
+    const now = Date.now();
     await Promise.all([...subagents.values()].map(async (m) => {
-        const ms = await readSubagentDurationMs(m.transcriptPath);
+        const ms = await readFinishedSubagentDurationMs(m.transcriptPath, now);
         if (ms !== undefined)
             out.set(m.toolUseId, ms);
     }));
     return out;
 }
 /**
- * The elapsed wall-clock of a sub-agent transcript: the delta between its first
- * and last `timestamp`. Scans for timestamps without a full JSON parse; returns
- * undefined if the file is missing or has < 2 timestamps.
+ * The elapsed wall-clock of a FINISHED sub-agent transcript, or undefined when it
+ * is missing, has < 2 timestamps, or still looks live (see {@link SUBAGENT_STALE_MS}).
  */
-async function readSubagentDurationMs(file) {
+async function readFinishedSubagentDurationMs(file, now) {
     const mtimeMs = await statMtimeMs(file);
+    const facts = await readSubagentFacts(file, mtimeMs);
+    if (facts.durationMs === undefined)
+        return undefined;
+    // No mtime (the file vanished between the stat and the read) ⇒ nothing is
+    // writing to it, so fall back to the structural check alone.
+    const quietMs = mtimeMs === undefined ? Infinity : now - mtimeMs;
+    if (!facts.endsWithEndTurn && quietMs < SUBAGENT_STALE_MS)
+        return undefined;
+    return facts.durationMs;
+}
+async function readSubagentFacts(file, mtimeMs) {
     if (mtimeMs !== undefined) {
-        const cached = mtimeCacheGet(durationCache, file, mtimeMs);
+        const cached = mtimeCacheGet(factsCache, file, mtimeMs);
         if (cached.hit)
             return cached.value;
     }
-    const value = await readSubagentDurationMsUncached(file);
-    // Cache even undefined (missing/malformed) so a repeat open of an unchanged,
-    // duration-less transcript doesn't re-read the whole file every time.
+    const value = await readSubagentFactsUncached(file);
+    // Cache even the empty result (missing/malformed) so a repeat open of an
+    // unchanged, duration-less transcript doesn't re-read the whole file every time.
     if (mtimeMs !== undefined)
-        mtimeCacheSet(durationCache, file, mtimeMs, value);
+        mtimeCacheSet(factsCache, file, mtimeMs, value);
     return value;
 }
-async function readSubagentDurationMsUncached(file) {
+async function readSubagentFactsUncached(file) {
     const raw = await fs.readFile(file, "utf8").catch(() => null);
     if (raw === null)
-        return undefined;
+        return { endsWithEndTurn: false };
+    return { durationMs: transcriptSpanMs(raw), endsWithEndTurn: endsWithEndTurn(raw) };
+}
+/** First→last `timestamp` delta. Scans for timestamps without a full JSON parse. */
+function transcriptSpanMs(raw) {
     const matches = [...raw.matchAll(/"timestamp":"([^"]+)"/g)];
     if (matches.length < 2)
         return undefined;
@@ -362,6 +476,25 @@ async function readSubagentDurationMsUncached(file) {
         return undefined;
     return last - first;
 }
+/** True when the transcript's last non-empty line is an assistant entry that
+ *  stopped with `end_turn`. Only that line is JSON-parsed. */
+function endsWithEndTurn(raw) {
+    const lines = raw.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const trimmed = lines[i].trim();
+        if (!trimmed)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            return parsed.type === "assistant" && parsed.message?.stop_reason === "end_turn";
+        }
+        catch {
+            // A torn final line means the writer is mid-append — definitively not settled.
+            return false;
+        }
+    }
+    return false;
+}
 /**
  * Compute each sub-agent's estimated API-rate cost (USD), keyed by toolUseId, as
  * the RECURSIVE total of the sub-agent PLUS every sub-agent it (transitively)
@@ -611,6 +744,13 @@ function attachSubagentFields(messages, taskUses, subagents, durations, costs) {
                 description: use.description,
                 prompt: use.prompt,
                 hasSubagent: subagents.has(use.toolUseId),
+                // Same hazard as the `pending` branch above, and for the same reason:
+                // a PAIRED `Task` does NOT mean the sub-agent is done — the SDK
+                // backgrounds it, so the tool_result lands in milliseconds while the
+                // sub-agent keeps working. `durations` is therefore gated on liveness at
+                // its source ({@link subagentDurations}) and holds an entry only for a
+                // sub-agent whose transcript has actually settled, so a still-running one
+                // gets `undefined` here and keeps its place in the bar (#725).
                 subagentDurationMs: durations.get(use.toolUseId),
                 subagentCostUsd: costs.get(use.toolUseId),
             },