@inflexa-ai/harness 0.16.0 → 0.18.0

package/dist/loop/run-agent.js

@@ -155,8 +155,12 @@ export async function runAgent(agent, initial, session, opts) {
      * in what they count. An error tool result is otherwise invisible to every sink —
      * it is not a thrown failure, so nothing reports it and the loop simply feeds it
      * back — and a run that ends badly is usually a run whose tool calls were failing.
+     *
+     * `details` and `durations` are positionally aligned with `calls`. `dispatchTools`
+     * measures a duration around the call itself, because this sink emits every finish
+     * event only after the whole round settles.
      */
-    const settleRound = async (calls, results, details) => {
+    const settleRound = async (calls, results, details, durations) => {
         const errored = [];
         for (let idx = 0; idx < calls.length; idx++) {
             const tu = calls[idx];
@@ -169,7 +173,15 @@ export async function runAgent(agent, initial, session, opts) {
                 toolErrorCount++;
                 errored.push(tu.toolName);
             }
-            await emit({ type: "tool-finished", source, toolUseId: tu.toolCallId, name: tu.toolName, outcome, ...detailField(details[idx]) });
+            await emit({
+                type: "tool-finished",
+                source,
+                toolUseId: tu.toolCallId,
+                name: tu.toolName,
+                outcome,
+                ...detailField(details[idx]),
+                ...durationField(durations[idx]),
+            });
         }
         return errored;
     };
@@ -226,8 +238,8 @@ export async function runAgent(agent, initial, session, opts) {
             for (const [idx, tu] of earlier.entries()) {
                 await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(earlierDetails[idx]) });
             }
-            const results = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-            const errored = await settleRound(earlier, results, earlierDetails);
+            const { results, durations } = await dispatchTools(earlier, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+            const errored = await settleRound(earlier, results, earlierDetails, durations);
             results.push(errorResult(trailing, TRUNCATED_TOOL_USE_ERROR));
             // The trailing call was never dispatched, but it reaches the model as an error
             // result like any other — so it counts, or `toolErrors` reports a cleaner run
@@ -256,8 +268,8 @@ export async function runAgent(agent, initial, session, opts) {
         for (const [idx, tu] of toolCalls.entries()) {
             await emit({ type: "tool-started", source, toolUseId: tu.toolCallId, name: tu.toolName, input: tu.input, ...detailField(details[idx]) });
         }
-        const results = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
-        const errored = await settleRound(toolCalls, results, details);
+        const { results, durations } = await dispatchTools(toolCalls, toolsById, toolCtx, isFatalLoopError, runStep, formatStepName.tool);
+        const errored = await settleRound(toolCalls, results, details, durations);
         if (errored.length > 0)
             log.debug("tool results returned errors", { iteration: i, tools: errored });
         messages.push({ role: "tool", content: results });
@@ -373,8 +385,22 @@ function markLastLoopAssistant(messages, initialCount) {
         }
     }
 }
+/**
+ * Dispatch one round of tool calls, and measure the time of each call.
+ *
+ * `results` and `durations` are positionally aligned with `toolUses`.
+ *
+ * Each measurement brackets the same unit that the loop awaits for that call. For a
+ * step-mode call that unit is `runStep`, thus the figure includes the durable-step
+ * wrapper. The wrapper is part of what the call cost, and a cached replay of a step
+ * is genuinely fast. A bracket inside the step would report a body that did not run.
+ */
 async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName) {
     const results = new Array(toolUses.length);
+    // The array starts with holes, which read as `undefined`. The element type
+    // says so, thus it agrees with what `settleRound` accepts. Every index is in
+    // fact assigned, because the mode partition below covers each call.
+    const durations = new Array(toolUses.length);
     const stepTools = [];
     const workflowTools = [];
     const inlineTools = [];
@@ -387,16 +413,28 @@ async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, run
         else
             stepTools.push({ tu, idx });
     }
-    await Promise.all(stepTools.map(({ tu, idx }) => runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError)).then((r) => {
-        results[idx] = r;
-    })));
+    await Promise.all(stepTools.map(({ tu, idx }) => {
+        const startedAt = performance.now();
+        return runStep(toolStepName(tu.toolName, tu.toolCallId), () => dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError)).then((r) => {
+            durations[idx] = elapsedMs(startedAt);
+            results[idx] = r;
+        });
+    }));
     for (const { tu, idx } of workflowTools) {
+        const startedAt = performance.now();
         results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        durations[idx] = elapsedMs(startedAt);
     }
     for (const { tu, idx } of inlineTools) {
+        const startedAt = performance.now();
         results[idx] = await dispatchTool(tu, toolsById, toolCtx(tu), isFatalLoopError);
+        durations[idx] = elapsedMs(startedAt);
     }
-    return results;
+    return { results, durations };
+}
+/** Whole milliseconds since `startedAt`, on the monotonic clock that took that mark. */
+function elapsedMs(startedAt) {
+    return Math.round(performance.now() - startedAt);
 }
 async function dispatchTool(tu, toolsById, ctx, isFatalLoopError) {
     const tool = toolsById.get(tu.toolName);
@@ -500,6 +538,16 @@ function outcomeOf(result) {
 function detailField(detail) {
     return detail === undefined ? {} : { detail };
 }
+/**
+ * The optional `durationMs` field, present only for a call that the loop measured.
+ *
+ * Spread rather than assigned, for the same reason as {@link detailField}: an
+ * unmeasured call emits no `durationMs` key. A zero here is a real measurement of a
+ * call that took under half a millisecond, and it is never a stand-in for no figure.
+ */
+function durationField(durationMs) {
+    return durationMs === undefined ? {} : { durationMs };
+}
 function hasDenial(results) {
     return results.some((r) => r.output.type === "execution-denied");
 }

package/dist/loop/tool-detail.d.ts

@@ -25,6 +25,46 @@ export type { ToolCallDetail };
  * channel.
  */
 export declare const DETAIL_MAX_LENGTH = 120;
+/**
+ * The bound a hook gives a free-form needle that it marks inside a detail.
+ *
+ * A needle is model-authored text of no fixed length, thus it is the one part of
+ * a detail that can run away. Left to {@link DETAIL_MAX_LENGTH}, a long needle
+ * takes the whole line, and the cut lands inside the mark that names it: the
+ * closing quote goes, and a second fact behind it goes with no trace. A hook
+ * bounds the needle first. Then the mark always closes, and the rest of the
+ * detail keeps its room.
+ *
+ * 32 code points shows the shape of a search — enough to recognize the needle a
+ * caller typed, and short enough that a target beside it survives whole.
+ */
+export declare const DETAIL_NEEDLE_MAX_LENGTH = 32;
+/**
+ * Cap `text` at `max` CODE POINTS, not UTF-16 units.
+ *
+ * A hook calls this to pre-empt the emit-site cap: that cap cuts the TAIL, so a
+ * detail with two parts loses the second one when the first runs long. One
+ * implementation serves both sites, thus a hook's own bound cuts and marks
+ * exactly as {@link normalizeDetail} does.
+ *
+ * `String.prototype.slice` cuts at a fixed unit index, which can land between the
+ * two halves of a surrogate pair and emit a lone surrogate — a terminal paints
+ * that as a replacement character, so the cap would corrupt the very tail it is
+ * supposed to merely shorten. Iterating the string yields whole code points.
+ *
+ * Code points, not display columns, is the right unit here: this cap is a safety
+ * valve against a runaway hook, so its job is to bound the payload. A column
+ * measurement would claim knowledge of the renderer's font metrics that the
+ * harness does not have — the host measures columns, because only the host knows
+ * how wide its own line is.
+ *
+ * A cut text carries `…` so that a reader can tell a shortened detail from a
+ * complete one. The mark costs one of the `max` code points, thus the cut goes to
+ * `max - 1`: a hard bound that overshoots by the width of its own mark is not a
+ * hard bound. `trimEnd` runs BEFORE the append, because a cut that lands on a
+ * space must give `word…` and not `word …`.
+ */
+export declare function capCodePoints(text: string, max: number): string;
 /**
  * Normalize whatever a hook returned into an emittable detail, or `undefined`.
  *

package/dist/loop/tool-detail.js

@@ -22,9 +22,28 @@ import { normalizeUnicode, redactSecrets } from "../input-sanitization.js";
  * channel.
  */
 export const DETAIL_MAX_LENGTH = 120;
+/**
+ * The bound a hook gives a free-form needle that it marks inside a detail.
+ *
+ * A needle is model-authored text of no fixed length, thus it is the one part of
+ * a detail that can run away. Left to {@link DETAIL_MAX_LENGTH}, a long needle
+ * takes the whole line, and the cut lands inside the mark that names it: the
+ * closing quote goes, and a second fact behind it goes with no trace. A hook
+ * bounds the needle first. Then the mark always closes, and the rest of the
+ * detail keeps its room.
+ *
+ * 32 code points shows the shape of a search — enough to recognize the needle a
+ * caller typed, and short enough that a target beside it survives whole.
+ */
+export const DETAIL_NEEDLE_MAX_LENGTH = 32;
 /**
  * Cap `text` at `max` CODE POINTS, not UTF-16 units.
  *
+ * A hook calls this to pre-empt the emit-site cap: that cap cuts the TAIL, so a
+ * detail with two parts loses the second one when the first runs long. One
+ * implementation serves both sites, thus a hook's own bound cuts and marks
+ * exactly as {@link normalizeDetail} does.
+ *
  * `String.prototype.slice` cuts at a fixed unit index, which can land between the
  * two halves of a surrogate pair and emit a lone surrogate — a terminal paints
  * that as a replacement character, so the cap would corrupt the very tail it is
@@ -35,10 +54,19 @@ export const DETAIL_MAX_LENGTH = 120;
  * measurement would claim knowledge of the renderer's font metrics that the
  * harness does not have — the host measures columns, because only the host knows
  * how wide its own line is.
+ *
+ * A cut text carries `…` so that a reader can tell a shortened detail from a
+ * complete one. The mark costs one of the `max` code points, thus the cut goes to
+ * `max - 1`: a hard bound that overshoots by the width of its own mark is not a
+ * hard bound. `trimEnd` runs BEFORE the append, because a cut that lands on a
+ * space must give `word…` and not `word …`.
  */
-function capCodePoints(text, max) {
+export function capCodePoints(text, max) {
     const points = Array.from(text);
-    return points.length <= max ? text : points.slice(0, max).join("").trimEnd();
+    if (points.length <= max)
+        return text;
+    const cut = points.slice(0, max - 1).join("");
+    return `${cut.trimEnd()}…`;
 }
 /**
  * Normalize whatever a hook returned into an emittable detail, or `undefined`.
@@ -78,8 +106,12 @@ export function normalizeDetail(raw) {
  * second time from the repaired value costs more than the case is worth.
  */
 export function computeDetail(tool, rawInput, log) {
+    // The guard tests for a function, not for presence. A packaged tool comes from
+    // an open list — an embedder contributes its own through the host-tools seam —
+    // so a `describeCall` that is not callable is reachable. Such a tool counts as
+    // undescribed, because the alternative is a TypeError on every one of its calls.
     const describeCall = tool.describeCall;
-    if (describeCall === undefined)
+    if (typeof describeCall !== "function")
         return undefined;
     try {
         // The parse is INSIDE the guard, not before it. `safeParse` returns an

package/dist/loop/types.d.ts

@@ -81,6 +81,19 @@ export type EmitEvent = {
     readonly outcome: ToolOutcome;
     /** The same detail the matching `tool-started` carried. */
     readonly detail?: ToolCallDetail;
+    /**
+     * The time around this call's own dispatch, in milliseconds.
+     *
+     * A host cannot measure this itself. The loop emits every
+     * `tool-started` of a round before it dispatches anything, and every
+     * `tool-finished` after the round settles. Thus a host that brackets
+     * the two events measures the round, and each call of a multi-call
+     * round reports the same figure.
+     *
+     * The field is optional, and it is absent when no measurement was
+     * taken. As a result a host can fall back to its own observation.
+     */
+    readonly durationMs?: number;
 };
 /**
  * A UI presentation event a tool streams to chat — an AI-SDK `data-*`

package/dist/memory/thread-history.d.ts

@@ -161,6 +161,16 @@ export interface ThreadHistory {
      * empty thread reports `empty-thread`.
      */
     retractLastTurn(threadId: string): ResultAsync<RetractOutcome, DbError>;
+    /**
+     * The greatest `messages.seq` in the thread, or `null` when the thread holds
+     * no messages. The read takes no lock: it reports the tail at the read
+     * moment, and a concurrent append can move the tail one row later.
+     *
+     * `appendTurn` computes the same value under its lock to place the next row.
+     * This read shares the table, not that statement. A lock here buys a caller
+     * no guarantee, because the tail can move one append later without it.
+     */
+    latestSeq(threadId: string): ResultAsync<number | null, DbError>;
 }
 /**
  * Drop the memoized instruments so the next `loadRecent` rebinds to a

package/dist/memory/thread-history.js

@@ -418,5 +418,16 @@ export function createThreadHistory(pool) {
             return tryMutation("thread-history.retractLastTurn.delete", () => client.query("DELETE FROM messages WHERE thread_id = $1 AND seq >= $2::bigint", [threadId, boundary])).map((res) => ({ kind: "retracted", messages: res.rowCount ?? 0 }));
         }));
     }
-    return { appendTurn, loadRecent, loadPage, retractLastTurn };
+    function latestSeq(threadId) {
+        // `MAX(seq)` over no rows is SQL NULL, so a thread with no messages reads
+        // as `null`, not as a seq — the absence a caller reads before it treats
+        // the value as an anchor. The `::text` cast carries a seq past 2^53 across
+        // the driver intact, the way every other read of this bigint column does,
+        // and `Number` makes the crossing in one place.
+        return tryQuery("thread-history.latestSeq", () => pool.query("SELECT MAX(seq)::text AS max_seq FROM messages WHERE thread_id = $1", [threadId])).map(({ rows }) => {
+            const maxSeq = rows[0]?.max_seq ?? null;
+            return maxSeq === null ? null : Number(maxSeq);
+        });
+    }
+    return { appendTurn, loadRecent, loadPage, retractLastTurn, latestSeq };
 }

package/dist/memory/thread-store.d.ts

@@ -10,20 +10,24 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Three lifecycle verbs with distinct guarantees. `archiveThread` is
- * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * A thread may name another as its parent, so the rows under one analysis form
+ * a forest rather than a flat list. The three lifecycle verbs each answer that
+ * edge differently, and the differences are the substance of this module.
+ *
+ * `archiveThread` is recoverable: it stamps `deleted_at` on the named thread
+ * and on every descendant, and because `getThread` and the default
  * `listThreads` filter `deleted_at IS NULL` an archived thread is
  * indistinguishable from an absent one while its row and every one of its
- * `messages` rows stay in storage. `unarchiveThread` clears the stamp and the
- * thread reads as it did; a listing widened with `includeArchived` is the only
- * way to obtain the id it takes, so the recovery is reachable by a host that
- * holds no thread ids it obtained elsewhere.
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp on ONE
+ * row and the thread reads as it did; a listing widened with `includeArchived`
+ * is the only way to obtain the id it takes, so the recovery is reachable by a
+ * host that holds no thread ids it obtained elsewhere.
  * `purgeThread` is not recoverable: it removes the `messages` rows and the
- * metadata row in one transaction, so a failure partway leaves both — never a
- * thread stripped of its transcript, nor a transcript with nothing naming it.
- * It is the thread-scoped member of this package's reclamation vocabulary —
- * `purgeAnalysis` reclaims an analysis's whole persisted footprint,
- * `purgeThread` one thread's.
+ * metadata rows of the whole subtree in one transaction, so a failure partway
+ * leaves both — never a thread stripped of its transcript, nor a transcript
+ * with nothing naming it. It is the thread-scoped member of this package's
+ * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
+ * persisted footprint, `purgeThread` one subtree's.
  *
  * A purge creates no orphan of its own, but it is NOT serialized against a
  * concurrent `appendTurn`: `messages` carries no foreign key to
@@ -31,17 +35,51 @@
  * metadata row. A turn committing after the purge therefore persists messages
  * under a `thread_id` that no longer resolves to an analysis, leaving them
  * unreachable by any later thread- or analysis-scoped reclamation. Stop writes
- * to a thread — unbind it from any live conversation — before purging it; this
- * store cannot observe a host's in-flight turns, so it does not enforce that.
+ * to every thread in the subtree — unbind each from any live conversation —
+ * before purging its root; this store cannot observe a host's in-flight turns,
+ * so it does not enforce that.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * The kind of session a thread holds. `conversation` is the analysis
+ * conversation the product has always had; `report` is a report session spawned
+ * from one.
+ *
+ * The set is closed rather than free-form because a thread's type is what
+ * selects the agent that runs it. That resolution is a separate capability, and
+ * it can only be exhaustive over a membership something can enumerate — a
+ * free-form column pushes an unmatched value into a fallback no reader has the
+ * list to write.
+ *
+ * The array is the single declaration and the union is derived from it, so the
+ * run-time check `createThread` needs — for a value that reached the store from
+ * outside the compiler's reach — cannot drift from the type callers program
+ * against.
+ */
+declare const THREAD_TYPES: readonly ["conversation", "report"];
+export type ThreadType = (typeof THREAD_TYPES)[number];
 /** One conversation thread's metadata, as returned by the store. */
 export interface Thread {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title: string | null;
+    /** Which kind of session this row holds. A thread created without one is a `conversation`. */
+    readonly threadType: ThreadType;
+    /** The thread this one was spawned from — `null` on a thread that stands on its own. */
+    readonly parentThreadId: string | null;
+    /**
+     * The parent's `messages.seq` at the moment of the spawn: the frozen point
+     * in the parent's transcript this thread was built on. `null` exactly when
+     * `parentThreadId` is — half the pair names nothing a consumer can resolve.
+     *
+     * It records the spawn point, not a promise that the prefix still reads the
+     * same: `retractLastTurn` can cut the parent's tail behind an anchor, so a
+     * reader must treat an anchor past the parent's current end as a normal
+     * state rather than a corruption.
+     */
+    readonly parentSeq: number | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
     /**
@@ -56,7 +94,51 @@ export interface CreateThreadInput {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title?: string | null;
+    /** Omitted is `conversation` — what a thread is when nothing says otherwise. */
+    readonly type?: ThreadType;
+    /**
+     * The thread this one is spawned from. It must belong to the same analysis
+     * as the child; whether it exists at all is the foreign key's verdict, not
+     * this store's.
+     */
+    readonly parentThreadId?: string;
+    /**
+     * The parent's `messages.seq` at the spawn. Supply it with `parentThreadId`
+     * or neither: the two are one fact — which transcript, and how much of it —
+     * and either half alone describes no place.
+     */
+    readonly parentSeq?: number;
 }
+/**
+ * A create the store refuses on its own, before any row is written. Distinct
+ * from `DbError`: nothing failed at the driver — the request described a thread
+ * the store will not write, and each variant carries the identifiers that say
+ * which values disagreed.
+ *
+ * Only the rules the store enforces itself live here. A `parentThreadId` naming
+ * no row is not one of them: the foreign key refuses that insert and
+ * `tryMutation` classifies the refusal as the `constraint_violation` variant of
+ * `DbError`.
+ */
+export type ThreadInputError = {
+    readonly type: "parent_analysis_mismatch";
+    readonly op: string;
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly parentThreadId: string;
+    readonly parentAnalysisId: string;
+} | {
+    readonly type: "parent_anchor_unpaired";
+    readonly op: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly parentSeq: number | null;
+} | {
+    readonly type: "unknown_thread_type";
+    readonly op: string;
+    readonly threadId: string;
+    readonly threadType: string;
+};
 export interface ListThreadsInput {
     readonly analysisId: string;
     readonly page?: number;
@@ -68,6 +150,20 @@ export interface ListThreadsInput {
      * widened back out of.
      */
     readonly includeArchived?: boolean;
+    /**
+     * Narrow to one kind of session, exact match. Omitting it narrows NOTHING —
+     * a caller that supplies no filter receives every type, which is what a
+     * session picker wants: a user browsing an analysis expects to reach a
+     * report session directly.
+     *
+     * That is the opposite polarity to `includeArchived`, which widens a listing
+     * that is narrow by default, and the difference is deliberate. An archived
+     * thread is hidden state — showing it takes an explicit ask. A report
+     * session is not hidden state, so nothing has to ask for it.
+     */
+    readonly type?: ThreadType;
+    /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
+    readonly parentThreadId?: string;
 }
 export interface ThreadPage {
     readonly threads: Thread[];
@@ -80,9 +176,16 @@ export interface ThreadStore {
     /**
      * Create a thread row. Idempotent on `thread_id` — a second create for an
      * existing id is a no-op that preserves the existing row (including its
-     * `created_at`). Returns the live row.
+     * `created_at`) and reads none of the supplied type, parent, or anchor. A
+     * caller that needs those persisted compares them against the returned row.
+     * Returns the live row.
+     *
+     * Refused with a `ThreadInputError`, no row written: a parent belonging to
+     * another analysis, a parent supplied without its anchor or an anchor
+     * without its parent, and a type outside the closed set. A parent naming no
+     * row is the foreign key's refusal and arrives as a `DbError`.
      */
-    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
+    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError | ThreadInputError>;
     /** The live thread by id, or `null` if absent or archived. */
     getThread(threadId: string): ResultAsync<Thread | null, DbError>;
     /**
@@ -91,26 +194,39 @@ export interface ThreadStore {
      */
     updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
     /**
-     * Soft-delete: stamp `deleted_at` so the thread leaves `getThread` and
-     * `listThreads`. The row and every one of its messages remain, and an
-     * already-archived thread keeps the stamp it got the first time.
+     * Soft-delete the subtree: stamp `deleted_at` on the named thread and on
+     * every descendant reachable through `parent_thread_id`, at any depth, so a
+     * hidden thread never leaves a visible child behind. Every row and every one
+     * of their messages remain, and any thread in the subtree that was already
+     * archived keeps the stamp it got the first time.
      */
     archiveThread(threadId: string): ResultAsync<void, DbError>;
     /**
-     * Clear `deleted_at`, returning the thread and its messages to view exactly
-     * as they read before the archive. No-op on a live or absent thread.
+     * Clear `deleted_at` on the named thread ALONE, returning it and its
+     * messages to view exactly as they read before the archive; every descendant
+     * is left as it was found. No-op on a live or absent thread.
+     *
+     * The asymmetry against `archiveThread` is what keeps the schema honest. A
+     * symmetric cascade would restore a child the user had archived on its own
+     * beforehand, so a row would have to record whether a cascade or a
+     * deliberate action set its tombstone — a fourth column carrying nothing
+     * else. With the asymmetry no row needs that distinction, and every archived
+     * thread is recovered the same way: by naming it, which a listing widened
+     * with `includeArchived` supplies.
      */
     unarchiveThread(threadId: string): ResultAsync<void, DbError>;
     /**
-     * Reclaim the thread's whole footprint: its `messages` rows and its
-     * `cortex_analysis_threads` row, removed together in one transaction.
-     * Unrecoverable — nothing of the thread survives, and no tombstone marks
-     * that it existed. A `thread_id` with no row succeeds as a no-op.
+     * Reclaim the subtree's whole footprint: the named thread, every descendant
+     * reachable through `parent_thread_id` at any depth, and the `messages` rows
+     * of every one of them, removed together in one transaction. Unrecoverable —
+     * nothing survives, and no tombstone marks that any of it existed. A
+     * `thread_id` with no row succeeds as a no-op.
      */
     purgeThread(threadId: string): ResultAsync<void, DbError>;
     /**
      * Threads for one analysis, newest-updated first, paginated. Live threads
-     * only unless `includeArchived` widens the set; `total` and `hasMore`
+     * only unless `includeArchived` widens the set, and every type under every
+     * parent unless `type` / `parentThreadId` narrow it; `total` and `hasMore`
      * always describe whichever set the page was drawn from.
      */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
@@ -121,3 +237,4 @@ export interface ThreadStore {
  * `cortex_analysis_threads` table is provisioned by the state-init DDL.
  */
 export declare function createThreadStore(pool: Pool): ThreadStore;
+export {};