@inflexa-ai/harness 0.14.2 → 0.15.0

package/dist/memory/content-to-cortex.d.ts

@@ -14,22 +14,46 @@
  *
  * Display cards are emitted live over the chat SSE stream but never persisted
  * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload.
+ * rebuilds them from the persisted tool-call part so they reappear on reload,
+ * and `resolveDetail` rebuilds each call's one-line detail the same way.
+ *
+ * A `tool-result` block is not rendered, but it is not ignored either: it is the
+ * only record of how its call ended. The blocks are indexed by `toolCallId`
+ * before conversion so each tool-call part can report its own outcome — without
+ * that pass every reloaded call reported success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
 import type { CortexMessage } from "@inflexa-ai/harness/contracts/message.js";
+import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 import type { ToolCardResolver } from "./reconstruct-cards.js";
 import type { StoredMessage } from "./thread-history.js";
+/**
+ * The resolvers a caller may supply, as one object.
+ *
+ * An options bag rather than a growing positional list: both are optional, both
+ * are function-typed, and a second positional parameter of the same shape is a
+ * call site that silently does the wrong thing when the two are swapped.
+ */
+export interface ContentToCortexOptions {
+    /** Rebuilds a display card (`data-plan`, `data-presentation`) from a persisted tool call. */
+    readonly resolveCard?: ToolCardResolver;
+    /** Rebuilds a call's one-line detail from its tool name and persisted input. */
+    readonly resolveDetail?: ToolDetailResolver;
+}
 /**
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
  * no renderable parts are dropped, and consecutive assistant rows are coalesced
  * into one message. The first row's `seq` becomes the stable message id.
- * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ * `options.resolveCard` reconstructs display cards from `tool_use` blocks and
+ * `options.resolveDetail` reconstructs each call's one-line detail; both are
+ * optional and each tool-call part reports its outcome either way.
  * A row carrying the interruption marker sets `interrupted: true` on the message
- * it lands in, including when coalesced into an assistant run.
+ * it lands in, including when coalesced into an assistant run; a row carrying a
+ * stored turn rollup sets `usage` the same way, so a reloaded conversation shows
+ * the cost the live turn showed without a second query.
  *
  * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
  * step (typically a single `tool_use`) as its own row, and the `tool_result`
@@ -46,4 +70,4 @@ import type { StoredMessage } from "./thread-history.js";
  * turn's lone user message followed by the next turn's), and merging them would
  * fabricate one bubble from two messages the user sent separately.
  */
-export declare function contentToCortexMessages(messages: readonly StoredMessage[], resolveCard?: ToolCardResolver): Promise<CortexMessage[]>;
+export declare function contentToCortexMessages(messages: readonly StoredMessage[], options?: ContentToCortexOptions): Promise<CortexMessage[]>;

package/dist/memory/content-to-cortex.js

@@ -14,39 +14,74 @@
  *
  * Display cards are emitted live over the chat SSE stream but never persisted
  * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload.
+ * rebuilds them from the persisted tool-call part so they reappear on reload,
+ * and `resolveDetail` rebuilds each call's one-line detail the same way.
+ *
+ * A `tool-result` block is not rendered, but it is not ignored either: it is the
+ * only record of how its call ended. The blocks are indexed by `toolCallId`
+ * before conversion so each tool-call part can report its own outcome — without
+ * that pass every reloaded call reported success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
+import { toolOutcomeForOutputType } from "../loop/tool-outcome.js";
 import { isInterruptedMessage, isSyntheticRecordMessage, isSyntheticUserMessage } from "./ai-sdk-message-storage.js";
-function genericToolCall(block) {
+/**
+ * How each stored call ended, keyed by tool-call id.
+ *
+ * A whole page is indexed before conversion because the pairing crosses rows: a
+ * call rides an `assistant` row and its result rides the `tool` row after it.
+ */
+function indexOutcomes(messages) {
+    const outcomes = new Map();
+    for (const { message } of messages) {
+        const content = message.content;
+        if (typeof content === "string")
+            continue;
+        for (const block of content) {
+            if (block.type !== "tool-result")
+                continue;
+            outcomes.set(block.toolCallId, toolOutcomeForOutputType(block.output.type));
+        }
+    }
+    return outcomes;
+}
+function genericToolCall(block, outcomes, resolveDetail) {
+    // No paired result is the shape of a transcript whose `tool` row was never
+    // appended (an aborted turn). Nothing failed, so `ok` is the honest report.
+    const outcome = outcomes.get(block.toolCallId) ?? "ok";
+    const detail = resolveDetail?.(block.toolName, block.input);
     return {
         type: "tool-call",
         toolCallId: block.toolCallId,
         toolName: block.toolName,
         status: "finished",
+        outcome,
+        ...(detail === undefined ? {} : { detail }),
     };
 }
-async function blockToPart(block, resolveCard) {
+async function blockToPart(block, outcomes, options) {
     if (block.type === "text")
         return { type: "text", text: block.text };
     if (block.type === "tool-call") {
-        const card = resolveCard ? await resolveCard({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.input }) : null;
-        return card ?? genericToolCall(block);
+        const card = options.resolveCard
+            ? await options.resolveCard({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.input })
+            : null;
+        return card ?? genericToolCall(block, outcomes, options.resolveDetail);
     }
     // reasoning, tool_result, file, and any other block — not rendered.
     return null;
 }
-async function rowToParts(message, resolveCard) {
+async function rowToParts(message, outcomes, options) {
     const content = message.content;
     if (typeof content === "string") {
         return content.length > 0 ? [{ type: "text", text: content }] : [];
     }
     const parts = [];
     for (const block of content) {
-        const part = await blockToPart(block, resolveCard);
+        const part = await blockToPart(block, outcomes, options);
         if (part)
             parts.push(part);
     }
@@ -56,9 +91,13 @@ async function rowToParts(message, resolveCard) {
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
  * no renderable parts are dropped, and consecutive assistant rows are coalesced
  * into one message. The first row's `seq` becomes the stable message id.
- * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ * `options.resolveCard` reconstructs display cards from `tool_use` blocks and
+ * `options.resolveDetail` reconstructs each call's one-line detail; both are
+ * optional and each tool-call part reports its outcome either way.
  * A row carrying the interruption marker sets `interrupted: true` on the message
- * it lands in, including when coalesced into an assistant run.
+ * it lands in, including when coalesced into an assistant run; a row carrying a
+ * stored turn rollup sets `usage` the same way, so a reloaded conversation shows
+ * the cost the live turn showed without a second query.
  *
  * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
  * step (typically a single `tool_use`) as its own row, and the `tool_result`
@@ -75,7 +114,8 @@ async function rowToParts(message, resolveCard) {
  * turn's lone user message followed by the next turn's), and merging them would
  * fabricate one bubble from two messages the user sent separately.
  */
-export async function contentToCortexMessages(messages, resolveCard) {
+export async function contentToCortexMessages(messages, options = {}) {
+    const outcomes = indexOutcomes(messages);
     const out = [];
     for (const message of messages) {
         // The loop's truncation nudge carries the `user` role only for the wire
@@ -94,17 +134,25 @@ export async function contentToCortexMessages(messages, resolveCard) {
         const isRecord = isSyntheticRecordMessage(message.message);
         if (isSyntheticUserMessage(message.message) && !isRecord)
             continue;
-        const parts = await rowToParts(message.message, resolveCard);
+        const parts = await rowToParts(message.message, outcomes, options);
         // The marker is read before the zero-parts drop so the flag can never be lost to it:
         // a marked row carries an interruption fact regardless of whether it renders any parts.
         // When such a row contributes no bubble of its own, the interruption belongs to the
         // assistant run it trailed, so fold the flag onto the previous emitted assistant.
         const interrupted = isInterruptedMessage(message.message);
         if (parts.length === 0) {
-            if (interrupted) {
-                const prev = out[out.length - 1];
-                if (prev && prev.role === "assistant")
+            // A row's stored rollup is a fact about the turn, not about what the row
+            // renders — so like the interruption marker it is read before the
+            // zero-parts drop and folded onto the assistant run it trailed. Without
+            // this, a turn whose last assistant row held only unrendered blocks
+            // (reasoning alone) would lose the figure to the drop, which is the exact
+            // disappearance persisting it exists to fix.
+            const prev = out[out.length - 1];
+            if (prev && prev.role === "assistant") {
+                if (interrupted)
                     prev.interrupted = true;
+                if (message.usage)
+                    prev.usage = message.usage;
             }
             continue;
         }
@@ -122,11 +170,19 @@ export async function contentToCortexMessages(messages, resolveCard) {
             prev.parts.push(...parts);
             if (interrupted)
                 prev.interrupted = true;
+            // Coalescing is what rebuilds the one-bubble-per-turn shape, and the rollup
+            // rides the turn's LAST assistant row — so the run keeps whichever of its
+            // rows carried one. Assigning rather than merging is deliberate: two rollups
+            // in one run would mean two turns were merged, which coalescing never does.
+            if (message.usage)
+                prev.usage = message.usage;
             continue;
         }
         const cortex = { id: String(message.seq), role, parts };
         if (interrupted)
             cortex.interrupted = true;
+        if (message.usage)
+            cortex.usage = message.usage;
         out.push(cortex);
     }
     return out;

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

@@ -23,6 +23,7 @@
 import type { ModelMessage } from "ai";
 import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
+import type { TokenUsageRollup } from "../contracts/usage.js";
 import { type DbError } from "../lib/db-result.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
 /** One stored message, as returned by the display read (`loadPage`). */
@@ -30,6 +31,15 @@ export interface StoredMessage {
     readonly seq: number;
     readonly envelope: StoredMessageEnvelope;
     readonly message: ModelMessage;
+    /**
+     * What providers reported for the whole TURN this row completed — present
+     * only on the last assistant row of a turn appended with a rollup, absent
+     * everywhere else. Not a per-row figure, and unrelated to the `tokens` count
+     * `loadRecent` windows by: that is an offline estimate stamped on every row,
+     * this is a provider's own report (see the `reported_usage` column comment in
+     * the state-init DDL).
+     */
+    readonly usage?: TokenUsageRollup;
 }
 /**
  * A page of stored messages plus pagination metadata. Pagination is
@@ -66,8 +76,18 @@ export interface ThreadHistory {
     /**
      * Append one conversation turn — every message written in a single
      * transaction with a `seq` monotonically increasing per thread.
+     *
+     * `turnUsage` is the turn's reported rollup, as `AgentFinish.turnUsage`
+     * carries it out of the loop and the `finish` event carries it to a live
+     * surface. It is stored on the LAST assistant message of the turn — the row a
+     * reader associates with the reply — so a reloaded transcript renders the
+     * figure the live turn showed. Optional at every layer: omitting it, and
+     * supplying one that reports no quantity at all, both leave the row without
+     * one, because a turn that reported nothing must not read back as a turn that
+     * cost zero. A turn writing no assistant message stores none and still
+     * succeeds — there is no row on which the figure would mean anything.
      */
-    appendTurn(threadId: string, messages: readonly ModelMessage[]): ResultAsync<void, DbError>;
+    appendTurn(threadId: string, messages: readonly ModelMessage[], turnUsage?: TokenUsageRollup): ResultAsync<void, DbError>;
     /**
      * Return a recent-turns window that fits `tokenBudget`, oldest-first,
      * snapped to a valid AI SDK model-message sequence. The window START advances

package/dist/memory/thread-history.js

@@ -24,6 +24,7 @@ import { metrics } from "@opentelemetry/api";
 import { ResultAsync, ok, okAsync } from "neverthrow";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.js";
 import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, } from "./ai-sdk-message-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
@@ -155,9 +156,20 @@ export const EVICTION_BLOCK_TURNS = 4;
  * provisioned by the project's state-init DDL.
  */
 export function createThreadHistory(pool) {
-    function appendTurn(threadId, messages) {
+    function appendTurn(threadId, messages, turnUsage) {
         if (messages.length === 0)
             return okVoid();
+        // A rollup that reports no quantity is stored as absent, not as a rollup of
+        // absences, so "no figure" has exactly one representation in storage.
+        // `hasReportedUsage` is the loop's own predicate for the same question,
+        // reused rather than restated so the write and the loop cannot drift.
+        const rollup = hasReportedUsage(turnUsage) ? JSON.stringify(turnUsage) : null;
+        // The rollup describes the turn, and the assistant reply is the row a reader
+        // associates with the answer. The LAST assistant row, not any of them: a
+        // serial-tool turn writes one assistant row per step and only the last ends
+        // the turn. -1 (a turn that persisted no reply — an abort before any output)
+        // matches no index below, so nothing is written and the append still succeeds.
+        const rollupRow = messages.reduce((last, m, i) => (m.role === "assistant" ? i : last), -1);
         return withTransaction(pool, "thread-history.appendTurn", (client) => 
         // Serialize concurrent appends on this thread — without the lock, two
         // transactions can both read the same MAX(seq) and collide on the
@@ -173,12 +185,14 @@ export function createThreadHistory(pool) {
         // re-throws it to force ROLLBACK (a returned `err` that does not
         // reach `withTransaction` would COMMIT silently).
         messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(
-        // `::json`, never `::jsonb` — see the column comment in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, tokens)
-                     VALUES ($1, $2, $3::json, $4)
+        // `message_envelope::json`, never `::jsonb`, and `reported_usage::jsonb`,
+        // never `::json` — see the column comments in the state-init DDL.
+        `INSERT INTO messages (thread_id, seq, message_envelope, tokens, reported_usage)
+                     VALUES ($1, $2, $3::json, $4, $5::jsonb)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
-                           tokens = EXCLUDED.tokens`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content)])).map(() => undefined)), okVoid()))
+                           tokens = EXCLUDED.tokens,
+                           reported_usage = EXCLUDED.reported_usage`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content), i === rollupRow ? rollup : null])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
         // the only other writer of it is the title update — so without this
@@ -226,6 +240,12 @@ export function createThreadHistory(pool) {
             // ORDER BY name to the output column), sorting the bigint as text:
             // "10" before "2". Scrambled order splits a tool-call/tool-result pair
             // across an intervening turn. The qualified name forces the bigint column.
+            //
+            // `reported_usage` is deliberately NOT selected. Windowing budgets on
+            // `tokens` — an offline estimate every row carries — and a turn that
+            // reported nothing has no rollup at all, so budgeting on the rollup
+            // would silently stop evicting on exactly those threads. The two are
+            // different measurements sharing a unit; see the column comments.
             `SELECT seq::text AS seq, message_envelope, tokens
          FROM messages WHERE thread_id = $1 ORDER BY messages.seq ASC`, [threadId]);
             const parsed = rows.map((row) => ({
@@ -291,12 +311,14 @@ export function createThreadHistory(pool) {
             // `seq::text AS seq` output alias (Postgres resolves an unqualified
             // ORDER BY name to the output column), sorting the bigint as text:
             // "10" before "2". The qualified name forces the bigint column.
-            `SELECT seq::text AS seq, message_envelope
+            `SELECT seq::text AS seq, message_envelope, reported_usage
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
             const stored = rows.map((r) => {
                 const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-                return { seq: Number(r.seq), envelope, message: envelope.message };
+                // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+                // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+                return { seq: Number(r.seq), envelope, message: envelope.message, ...(r.reported_usage === null ? {} : { usage: r.reported_usage }) };
             });
             const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
             const total = turns.length;

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

@@ -10,9 +10,29 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
- * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
- * survive a delete and a tombstoned thread is indistinguishable from absent.
+ * Three lifecycle verbs with distinct guarantees. `archiveThread` is
+ * recoverable: it stamps `deleted_at`, 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.
+ * `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.
+ *
+ * A purge creates no orphan of its own, but it is NOT serialized against a
+ * concurrent `appendTurn`: `messages` carries no foreign key to
+ * `cortex_analysis_threads`, and the append deliberately tolerates a missing
+ * 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.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
@@ -24,6 +44,13 @@ export interface Thread {
     readonly title: string | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
+    /**
+     * The archive tombstone — `null` on a live thread, the moment it left view
+     * on an archived one. Required rather than optional: a row is always one or
+     * the other, so a caller listing archived threads has no `undefined` case to
+     * fall through and render a tombstoned conversation as live.
+     */
+    readonly deletedAt: Date | null;
 }
 export interface CreateThreadInput {
     readonly threadId: string;
@@ -34,6 +61,13 @@ export interface ListThreadsInput {
     readonly analysisId: string;
     readonly page?: number;
     readonly perPage?: number;
+    /**
+     * Widen the listing to archived threads alongside live ones. It widens, it
+     * does not switch: a caller wanting only the archived rows filters the
+     * result on `deletedAt`, which an archived-only listing could not be
+     * widened back out of.
+     */
+    readonly includeArchived?: boolean;
 }
 export interface ThreadPage {
     readonly threads: Thread[];
@@ -49,13 +83,36 @@ export interface ThreadStore {
      * `created_at`). Returns the live row.
      */
     createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
-    /** The live thread by id, or `null` if absent or soft-deleted. */
+    /** The live thread by id, or `null` if absent or archived. */
     getThread(threadId: string): ResultAsync<Thread | null, DbError>;
-    /** Set only the title (and bump `updated_at`). No-op on a missing/deleted row. */
+    /**
+     * Set only the title, bumping `updated_at` forward — never behind the stamp
+     * the row already carries. No-op on a missing/archived row.
+     */
     updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
-    /** Soft-delete: set `deleted_at`. The row and its messages remain. */
-    deleteThread(threadId: string): ResultAsync<void, DbError>;
-    /** Live threads for one analysis, newest-updated first, paginated. */
+    /**
+     * 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.
+     */
+    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.
+     */
+    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.
+     */
+    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`
+     * always describe whichever set the page was drawn from.
+     */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
 }
 /**

package/dist/memory/thread-store.js

@@ -10,12 +10,32 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
- * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
- * survive a delete and a tombstoned thread is indistinguishable from absent.
+ * Three lifecycle verbs with distinct guarantees. `archiveThread` is
+ * recoverable: it stamps `deleted_at`, 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.
+ * `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.
+ *
+ * A purge creates no orphan of its own, but it is NOT serialized against a
+ * concurrent `appendTurn`: `messages` carries no foreign key to
+ * `cortex_analysis_threads`, and the append deliberately tolerates a missing
+ * 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.
  */
 import { okAsync } from "neverthrow";
-import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 function toThread(row) {
     return {
         threadId: row.thread_id,
@@ -23,6 +43,7 @@ function toThread(row) {
         title: row.title,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
+        deletedAt: row.deleted_at,
     };
 }
 const DEFAULT_PER_PAGE = 100;
@@ -37,43 +58,86 @@ export function createThreadStore(pool) {
         return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title)
          VALUES ($1, $2, $3)
          ON CONFLICT (thread_id) DO NOTHING
-         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
+         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
             if (rows[0])
                 return okAsync(toThread(rows[0]));
             // Row already existed — ON CONFLICT DO NOTHING returns nothing. Read it
-            // back (it may be soft-deleted; return it regardless so the caller sees
+            // back (it may be archived; return it regardless so the caller sees
             // the existing row's identity).
-            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
            FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
         });
     }
     function getThread(threadId) {
-        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
          FROM cortex_analysis_threads
          WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
     function updateTitle(threadId, title) {
-        return tryMutation("thread-store.updateTitle", () => pool.query(`UPDATE cortex_analysis_threads
-         SET title = $2, updated_at = NOW()
+        return tryMutation("thread-store.updateTitle", () => pool.query(
+        // `updated_at` is the listing's activity clock, and a rename is not its
+        // only writer — a turn append touches the same column, and a rename that
+        // starts before one can still reach the row after it. Taking the LATER of
+        // the two makes the bump forward-only, so a rename can never pull the
+        // column back behind a stamp the row already carries, no matter which
+        // writer set it or how long this statement waited to run. `NOW()` cannot
+        // give that: it reads this transaction's START time, not the moment the
+        // row is actually written.
+        `UPDATE cortex_analysis_threads
+         SET title = $2, updated_at = GREATEST(updated_at, clock_timestamp())
          WHERE thread_id = $1 AND deleted_at IS NULL
-         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
+         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
-    function deleteThread(threadId) {
-        return tryMutation("thread-store.deleteThread", () => pool.query(`UPDATE cortex_analysis_threads
+    function archiveThread(threadId) {
+        return tryMutation("thread-store.archiveThread", () => pool.query(
+        // The tombstone guard is what makes a second archive change nothing:
+        // the stamp records when the thread left view, and re-stamping it
+        // would push that moment forward on every repeat.
+        `UPDATE cortex_analysis_threads
          SET deleted_at = NOW()
          WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(() => undefined);
     }
+    function unarchiveThread(threadId) {
+        return tryMutation("thread-store.unarchiveThread", () => pool.query(
+        // `updated_at` is untouched on purpose: it orders the listing by
+        // conversation activity, and restoring a thread to view is not
+        // activity — a restored thread lands back where its last turn left it.
+        `UPDATE cortex_analysis_threads
+         SET deleted_at = NULL
+         WHERE thread_id = $1 AND deleted_at IS NOT NULL`, [threadId])).map(() => undefined);
+    }
+    function purgeThread(threadId) {
+        // One transaction for both statements: `messages` is attributable to an
+        // analysis only by joining through `cortex_analysis_threads`, so a metadata
+        // row removed without its messages strands them beyond the reach of any
+        // later reclamation. Either the pair goes or neither does.
+        return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query("DELETE FROM messages WHERE thread_id = $1", [threadId]))
+            .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query("DELETE FROM cortex_analysis_threads WHERE thread_id = $1", [threadId])))
+            .map(() => undefined));
+    }
     function listThreads(input) {
         const perPage = Math.min(Math.max(input.perPage ?? DEFAULT_PER_PAGE, 1), MAX_PER_PAGE);
         const page = Math.max(input.page ?? 0, 0);
         const offset = page * perPage;
+        // The count and the page are two statements over what has to be one set:
+        // a total drawn from a different predicate than the page's would report a
+        // size the caller can never page to. Writing the row scope once — one of
+        // two fixed fragments, never caller text — makes them unable to disagree.
+        //
+        // The widened scope is the one that cannot use the table's index, which is
+        // partial on `deleted_at IS NULL`: dropping the predicate drops the index
+        // with it, so an archived-inclusive listing scans. Deliberate — the live
+        // listing is the hot path and keeps its index, while widening is a rare,
+        // user-initiated recovery. A deployment that made it routine would want a
+        // plain `analysis_id` index beside the partial one, not this listing changed.
+        const scope = input.includeArchived ? "analysis_id = $1" : "analysis_id = $1 AND deleted_at IS NULL";
         return tryQuery("thread-store.listThreads.count", () => pool.query(`SELECT COUNT(*)::text AS count
          FROM cortex_analysis_threads
-         WHERE analysis_id = $1 AND deleted_at IS NULL`, [input.analysisId])).andThen((totalResult) => {
+         WHERE ${scope}`, [input.analysisId])).andThen((totalResult) => {
             const total = Number(totalResult.rows[0].count);
-            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
            FROM cortex_analysis_threads
-           WHERE analysis_id = $1 AND deleted_at IS NULL
+           WHERE ${scope}
            ORDER BY updated_at DESC, thread_id
            LIMIT $2 OFFSET $3`, [input.analysisId, perPage, offset])).map(({ rows }) => ({
                 threads: rows.map(toThread),
@@ -84,5 +148,5 @@ export function createThreadStore(pool) {
             }));
         });
     }
-    return { createThread, getThread, updateTitle, deleteThread, listThreads };
+    return { createThread, getThread, updateTitle, archiveThread, unarchiveThread, purgeThread, listThreads };
 }

package/dist/provenance/collector.d.ts

@@ -165,9 +165,11 @@ export declare class ProvenanceCollector {
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
      * is not a content-attestable file of this analysis: one resolving to a
      * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
-     * tracks as an open), or one resolving outside the analysis tree (e.g.
-     * `/{resourceId}/..`, the container root). Neither may reach registration.
-     * Mirrors the output-side non-file and out-of-bounds drops.
+     * tracks as an open), one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root), or one naming a path that is not
+     * there at reconcile (a capture layer reports attempted opens, so a read
+     * that failed is reported like one that succeeded). None may reach
+     * registration. Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref: InputRef): void;
     /**

package/dist/provenance/collector.js

@@ -278,9 +278,11 @@ export class ProvenanceCollector {
      * are shared objects). `reconcileManifestWithDisk` calls this for a read that
      * is not a content-attestable file of this analysis: one resolving to a
      * directory (e.g. an `ls` / `list.files` of a mount, which the inotify frame
-     * tracks as an open), or one resolving outside the analysis tree (e.g.
-     * `/{resourceId}/..`, the container root). Neither may reach registration.
-     * Mirrors the output-side non-file and out-of-bounds drops.
+     * tracks as an open), one resolving outside the analysis tree (e.g.
+     * `/{resourceId}/..`, the container root), or one naming a path that is not
+     * there at reconcile (a capture layer reports attempted opens, so a read
+     * that failed is reported like one that succeeded). None may reach
+     * registration. Mirrors the output-side non-file and out-of-bounds drops.
      */
     dropInput(ref) {
         for (const [key, val] of this.inputAccesses) {