sensorium-mcp 3.1.2 → 3.1.3-board.10

package/dist/data/memory/thread-registry.js

@@ -5,7 +5,9 @@
  * (root, daily, branch, worker) with their configuration and status.
  */
 import { nowISO } from "./utils.js";
+import { Optional } from "../optional.js";
 import { restoreNotesForThread } from "./note-archival.js";
+import { MINTED_THREAD_ID_FLOOR } from "./schema-ddl.js";
 export class ThreadRepository {
     registerThread(db, entry) {
         return registerThread(db, entry);
@@ -35,6 +37,7 @@ function rowToEntry(row) {
         name: row.name,
         type: row.type,
         rootThreadId: row.root_thread_id ?? null,
+        notifyThreadId: row.notify_thread_id ?? null, // eslint-disable-line no-restricted-syntax -- nullable DB column, mirrors sibling rootThreadId at the thread_registry row boundary
         badge: row.badge,
         client: row.client,
         maxRetries: row.max_retries,
@@ -55,21 +58,54 @@ function rowToEntry(row) {
     };
 }
 // ─── CRUD ────────────────────────────────────────────────────────────────────
+/**
+ * The row seam, and the one place the minted-id rule is stated for `thread_registry`.
+ *
+ * A worker's identity is MINTED ({@link mintThreadId}, called from `birthWorker`), so a
+ * `type = 'worker'` row below {@link MINTED_THREAD_ID_FLOOR} is not a worker anything
+ * mints — it is a Telegram topic number wearing a worker's type, and every id-reuse
+ * failure this line has chased (a worker inheriting an earlier occupant's lifecycle, a
+ * sweep deleting a live thread's forum topic because the id IS the topic) starts there.
+ *
+ * It is refused HERE because this statement is where `type` enters the table: the INSERT
+ * writes `entry.type`, and the ON CONFLICT arm below either PRESERVES the stored type
+ * (while `keep_alive = 1`) or writes `excluded.type`, which is this same `entry.type`.
+ * No other writer introduces one — `UpdateThreadPatch` has no `type` field, and
+ * `handleConvertToRoot`'s direct UPDATE writes the literal 'root'. A preserved type was
+ * therefore introduced by an earlier call through this guard, or predates migration 39,
+ * which purged what did.
+ *
+ * It THROWS where the entrances above it answer in prose. `handleCreateThread` and
+ * `handleStartThread` refuse their own callers with a sentence naming the one way to get
+ * a worker, because those callers are an agent or an HTTP client that can act on it;
+ * an entry arriving here already carries the contradiction, and there is no row this
+ * function could write instead that the caller asked for.
+ */
 export function registerThread(db, entry) {
+    if (entry.type === "worker" && entry.threadId < MINTED_THREAD_ID_FLOOR) {
+        throw new Error(`registerThread: refusing to write a worker row on thread_id ${entry.threadId}, which is below ` +
+            `MINTED_THREAD_ID_FLOOR (${MINTED_THREAD_ID_FLOOR}) — a worker's id is minted, and a number in ` +
+            `the Telegram topic range names a topic rather than a worker. Mint the id first (birthWorker), ` +
+            `or register this row as the type it actually is.`);
+    }
     const now = nowISO();
     // Root and branch threads are the persistent tier: keep-alive (watcher
-    // respawn) and daily rotation (consolidation) are on by default. Daily and
-    // worker threads stay off. Explicit values still win over the type default.
+    // respawn) is on by default. The nightly MEMORY pass runs for every
+    // non-worker thread regardless of this flag (see getConsolidationThreads),
+    // so daily_rotation now only gates the OPT-IN session RESTART and therefore
+    // defaults OFF — a fresh root is never force-restarted unless explicitly
+    // enabled. Explicit values still win over the type default.
     const persistentByDefault = entry.type === "root" || entry.type === "branch";
-    const dailyRotation = entry.dailyRotation ?? persistentByDefault;
+    const dailyRotation = entry.dailyRotation ?? false;
     const keepAlive = entry.keepAlive ?? persistentByDefault;
     db.prepare(`INSERT INTO thread_registry
-       (thread_id, name, type, root_thread_id, badge, client, max_retries, cooldown_ms, keep_alive, daily_rotation, working_directory, created_at, last_active_at, status)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')
+       (thread_id, name, type, root_thread_id, notify_thread_id, badge, client, max_retries, cooldown_ms, keep_alive, daily_rotation, working_directory, created_at, last_active_at, status)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')
      ON CONFLICT(thread_id) DO UPDATE SET
        name = excluded.name,
        type = CASE WHEN thread_registry.keep_alive = 1 THEN thread_registry.type ELSE excluded.type END,
        root_thread_id = excluded.root_thread_id,
+       notify_thread_id = excluded.notify_thread_id,
        badge = excluded.badge,
        client = CASE WHEN thread_registry.keep_alive = 1 THEN thread_registry.client ELSE excluded.client END,
        max_retries = excluded.max_retries,
@@ -78,17 +114,82 @@ export function registerThread(db, entry) {
        daily_rotation = CASE WHEN thread_registry.keep_alive = 1 THEN thread_registry.daily_rotation ELSE excluded.daily_rotation END,
        working_directory = COALESCE(excluded.working_directory, thread_registry.working_directory),
        last_active_at = excluded.last_active_at,
-       status = 'active'`).run(entry.threadId, entry.name, entry.type, entry.rootThreadId ?? null, entry.badge ?? "root", entry.client ?? "claude", entry.maxRetries ?? 5, entry.cooldownMs ?? 300000, keepAlive ? 1 : 0, dailyRotation ? 1 : 0, entry.workingDirectory ?? null, now, now);
+       status = 'active',
+       -- Re-registering an archived thread revives it, so its archive stamp is
+       -- no longer true. Cleared with the status in the same statement, keeping
+       -- "archived_at is set exactly while status = 'archived'" an invariant the
+       -- purge anchor can rely on.
+       archived_at = NULL
+     -- A row a purge has marked is not revived: its files are being removed and
+     -- its rows are next (see "The row is the lock" below).
+     WHERE thread_registry.purging_at IS NULL`).run(entry.threadId, entry.name, entry.type, entry.rootThreadId ?? null, entry.notifyThreadId ?? null, // eslint-disable-line no-restricted-syntax -- nullable DB column, mirrors sibling rootThreadId at the thread_registry row boundary
+    entry.badge ?? "root", entry.client ?? "claude", entry.maxRetries ?? 5, entry.cooldownMs ?? 300000, keepAlive ? 1 : 0, dailyRotation ? 1 : 0, entry.workingDirectory ?? null, now, now);
+    // The upsert's WHERE leaves a row a purge has marked untouched, and a marked row
+    // is still archived, so reading the mark back is the refusal.
+    if (isThreadMarkedForPurge(db, entry.threadId)) {
+        throw new Error(`registerThread: thread ${entry.threadId} is being permanently deleted — register it again once the delete has finished`);
+    }
     const result = getThread(db, entry.threadId);
     if (!result) {
         throw new Error(`registerThread: failed to retrieve thread after insert (threadId=${entry.threadId})`);
     }
     return result;
 }
+/**
+ * Allocate a thread id that no thread has ever held and none ever will again —
+ * GIVEN the allocating INSERT autocommits, which is what the first guard enforces.
+ * Inside an enclosing `db.transaction`, SQLite's AUTOINCREMENT mark rolls back with
+ * everything else and the next mint is handed the same number (measured), so the
+ * promise is not available mid-transaction and is refused rather than weakened.
+ *
+ * That refusal breaks no correct caller, because the sound order is mint, commit,
+ * then register: the id has to be durable before any row, file, process or wire
+ * message names it. A caller wanting mint-and-register atomically still mints first
+ * and tolerates the gap on a crash — a minted-never-used id is this design's native
+ * waste product, and never reusing one is exactly what makes those gaps free.
+ *
+ * Why the sequence is shaped the way it is — and why the mark survives a hard
+ * `deleteThread` and the 180-day purge — is argued on THREAD_ID_SEQUENCE_DDL. The
+ * trim that keeps the table at one row carries a WHERE and so cannot lower it.
+ *
+ * The floor is asserted rather than assumed. An id below it is a Telegram topic
+ * number as far as every reader of `thread_registry.thread_id` is concerned, and the
+ * two states that produce one — an unseeded sequence, or a lowered floor — are
+ * both silent. Refusing to mint is the only answer a caller cannot paper over.
+ */
+export function mintThreadId(db) {
+    if (db.inTransaction) {
+        throw new Error(`mintThreadId: refusing to mint inside a transaction — a rollback would discard the ` +
+            `allocating row and reissue its id, so the id would not be mint-once. Mint and let it ` +
+            `commit first, then open the transaction that records it.`);
+    }
+    const allocated = db
+        .prepare(`INSERT INTO thread_id_sequence (minted_at) VALUES (?)`)
+        .run(nowISO()).lastInsertRowid;
+    const minted = Number(allocated);
+    if (!Number.isSafeInteger(minted) || minted < MINTED_THREAD_ID_FLOOR) {
+        throw new Error(`mintThreadId: thread_id_sequence produced ${allocated}, which is not a safe integer at or above MINTED_THREAD_ID_FLOOR (${MINTED_THREAD_ID_FLOOR})`);
+    }
+    db.prepare(`DELETE FROM thread_id_sequence WHERE id < ?`).run(minted);
+    return minted;
+}
 export function getThread(db, threadId) {
     const row = db.prepare(`SELECT * FROM thread_registry WHERE thread_id = ?`).get(threadId);
     return row ? rowToEntry(row) : null;
 }
+/** Registry badge marking an ephemeral task-board card worker. */
+export const BOARD_WORKER_BADGE = "board-worker";
+/**
+ * Whether a thread's own episodic memory writes are suppressed. Currently true
+ * for ephemeral board-card workers, whose state lives in card comments rather
+ * than Sensorium episodes. Named for the memory concern so the episode layer
+ * asks a memory-domain question and never learns the board badge value.
+ */
+export function suppressesEpisodicMemory(db, threadId) {
+    return Optional.fromNullable(getThread(db, threadId))
+        .map((thread) => thread.badge === BOARD_WORKER_BADGE)
+        .orElse(false);
+}
 export function getThreadByName(db, name) {
     const row = db
         .prepare(`SELECT * FROM thread_registry WHERE name = ? AND status = 'active' ORDER BY last_active_at DESC LIMIT 1`)
@@ -107,9 +208,15 @@ export function getRootThreads(db) {
         .all();
     return rows.map(rowToEntry);
 }
-export function getDailyRotationThreads(db) {
+/**
+ * All non-worker, non-archived threads. The nightly memory pass (consolidation,
+ * reflection, narrative) runs for every one of these — memory integrity is
+ * required by all threads, not just those opted into session rotation. Workers
+ * are excluded because their memory is no-persist (discarded on decommission).
+ */
+export function getConsolidationThreads(db) {
     const rows = db
-        .prepare(`SELECT * FROM thread_registry WHERE daily_rotation = 1 AND type != 'worker' AND status != 'archived' ORDER BY created_at DESC`)
+        .prepare(`SELECT * FROM thread_registry WHERE type != 'worker' AND status != 'archived' ORDER BY created_at DESC`)
         .all();
     return rows.map(rowToEntry);
 }
@@ -146,8 +253,13 @@ export function updateThread(db, threadId, updates) {
         params.push(updates.name);
     }
     if (updates.status !== undefined) {
-        setClauses.push("status = ?");
-        params.push(updates.status);
+        // `archived_at` is DERIVED from the status in this one general status write, so
+        // "archived_at is set exactly while status = 'archived'" holds for every path that
+        // archives or revives a thread through here, with no caller stamping it by hand.
+        // It is the purge window's anchor. A row that is already archived keeps its
+        // stamp (COALESCE): re-archiving does not restart the clock it was archived on.
+        setClauses.push("status = ?", "archived_at = CASE WHEN ? = 'archived' THEN COALESCE(archived_at, ?) END");
+        params.push(updates.status, updates.status, nowISO());
     }
     if (updates.lastActiveAt !== undefined) {
         setClauses.push("last_active_at = ?");
@@ -200,14 +312,25 @@ export function updateThread(db, threadId, updates) {
     if (setClauses.length === 0)
         return false;
     params.push(threadId);
+    // A status write is a door like every start: a row a purge has marked keeps its
+    // status, or the sweep's mid-purge finisher would delete a thread revived here.
+    // And a 'spawning' row is held by a start (claimThreadStart): archiving it would
+    // hand it to the purge while that start is still writing the id's files (inc66 M2).
+    const statusGuard = updates.status === undefined
+        ? ""
+        : " AND purging_at IS NULL" +
+            (updates.status === "archived" ? " AND status <> 'spawning'" : "");
     const result = db
-        .prepare(`UPDATE thread_registry SET ${setClauses.join(", ")} WHERE thread_id = ?`)
+        .prepare(`UPDATE thread_registry SET ${setClauses.join(", ")} WHERE thread_id = ?${statusGuard}`)
         .run(...params);
     return result.changes > 0;
 }
+/** Archive a row. False when there is no row, a start holds it ('spawning'), or a
+ *  purge has marked it — re-stamping archived_at under a purge would be a false 200. */
 export function archiveThread(db, threadId) {
     const result = db
-        .prepare(`UPDATE thread_registry SET status = 'archived', keep_alive = 0, clean_shutdown = 1, archived_at = ? WHERE thread_id = ?`)
+        .prepare(`UPDATE thread_registry SET status = 'archived', keep_alive = 0, clean_shutdown = 1, archived_at = ?
+       WHERE thread_id = ? AND status <> 'spawning' AND purging_at IS NULL`)
         .run(nowISO(), threadId);
     return result.changes > 0;
 }
@@ -219,7 +342,8 @@ export function unarchiveThread(db, threadId) {
     // transaction rolls the status change back on any restore failure.
     return db.transaction(() => {
         const result = db
-            .prepare(`UPDATE thread_registry SET status = 'active', keep_alive = 1, archived_at = NULL WHERE thread_id = ? AND status = 'archived'`)
+            .prepare(`UPDATE thread_registry SET status = 'active', keep_alive = 1, archived_at = NULL
+         WHERE thread_id = ? AND status = 'archived' AND purging_at IS NULL`)
             .run(threadId);
         if (result.changes === 0)
             return false;
@@ -232,50 +356,219 @@ export function unarchiveThread(db, threadId) {
         return true;
     })();
 }
-export function getArchivedThreads(db) {
+/**
+ * Archived threads, workers EXCLUDED by default.
+ *
+ * The exclusion is right for the overview this feed was written for — a swarm
+ * run leaves dozens of decommissioned workers that would bury the handful of
+ * roots and branches an operator actually recognises. It was wrong as the ONLY
+ * answer: this is the single feed behind the archived-threads tab, which is the
+ * single place the permanent delete can be invoked from, and 220 of the 225
+ * per-thread config dirs on the live host (230 of its 320 MB) belong to exactly
+ * the archived workers it hid. The delete API itself never had a type filter —
+ * only the list did — so the bytes were unreachable rather than protected.
+ *
+ * `includeWorkers` is opt-in so every existing caller keeps the behaviour it
+ * was written against.
+ */
+export function getArchivedThreads(db, opts = {}) {
+    const workerFilter = opts.includeWorkers ? "" : ` AND type != 'worker'`;
     const rows = db
-        .prepare(`SELECT * FROM thread_registry WHERE status = 'archived' AND type != 'worker' ORDER BY archived_at DESC, last_active_at DESC`)
+        .prepare(`SELECT * FROM thread_registry WHERE status = 'archived'${workerFilter}
+       ORDER BY archived_at DESC, last_active_at DESC`)
         .all();
     return rows.map(rowToEntry);
 }
+/**
+ * Drop ONLY the registry row. Not a purge, and not reachable from the operator's
+ * delete any more — that goes through `purgeThread`, which takes every dependent
+ * table with it.
+ *
+ * It stays because worker-birth's PRE-SPAWN teardown wants exactly this: a row it
+ * registered moments ago, for a worker no process has run as, so nothing has been
+ * written against the id yet and there is nothing for a purge to find.
+ * `purgeThread` would refuse that row (no purge marked it: it is active, not
+ * archived). Do not reach for this to retire a thread that has ever run.
+ */
 export function deleteThread(db, threadId) {
     const result = db.prepare(`DELETE FROM thread_registry WHERE thread_id = ?`).run(threadId);
     return result.changes > 0;
 }
+// ─── Purge ───────────────────────────────────────────────────────────────────
 /**
- * Purge archived threads older than `maxAgeMs` (default 180 days).
- * Deletes the thread's associated data and registry entry.
- * Returns the number of threads purged.
+ * How long an archived thread survives before the daily sweep purges it.
+ *
+ * Was 180 days. The sweep is a floor, not the only way out — an archived thread
+ * now also has an explicit, operator-driven permanent delete (purgeThread +
+ * purgeThreadFiles, surfaced as `DELETE /api/threads/:id?hard=true`). With a
+ * deliberate path available, the automatic one no longer has to be the thing
+ * that reclaims disk, so the window is long enough that nothing is ever lost to
+ * a timer the operator forgot about. Exported so operator-facing text states
+ * the real number instead of a stale literal.
  */
-export function purgeOldArchivedThreads(db, maxAgeMs = 180 * 24 * 60 * 60 * 1000) {
-    const cutoff = new Date(Date.now() - maxAgeMs).toISOString();
-    const rows = db
-        .prepare(`SELECT thread_id FROM thread_registry
-     WHERE status = 'archived' AND last_active_at < ?`)
-        .all(cutoff);
-    if (rows.length === 0)
-        return 0;
-    const deleteEmbeddings = db.prepare(`DELETE FROM note_embeddings WHERE note_id IN (SELECT note_id FROM semantic_notes WHERE thread_id = ?)`);
-    const deleteNarratives = db.prepare(`DELETE FROM temporal_narratives WHERE thread_id = ?`);
-    const deleteVoiceSignatures = db.prepare(`DELETE FROM voice_signatures WHERE episode_id IN (SELECT episode_id FROM episodes WHERE thread_id = ?)`);
-    const deleteNotes = db.prepare(`DELETE FROM semantic_notes WHERE thread_id = ?`);
-    const deleteEpisodes = db.prepare(`DELETE FROM episodes WHERE thread_id = ?`);
-    const deleteSentMessages = db.prepare(`DELETE FROM sent_messages WHERE thread_id = ?`);
-    const deleteTopicRegistry = db.prepare(`DELETE FROM topic_registry WHERE thread_id = ?`);
-    const deleteRegistry = db.prepare(`DELETE FROM thread_registry WHERE thread_id = ?`);
-    db.transaction(() => {
-        for (const { thread_id } of rows) {
-            deleteEmbeddings.run(thread_id);
-            deleteNarratives.run(thread_id);
-            deleteVoiceSignatures.run(thread_id);
-            deleteNotes.run(thread_id);
-            deleteEpisodes.run(thread_id);
-            deleteSentMessages.run(thread_id);
-            deleteTopicRegistry.run(thread_id);
-            deleteRegistry.run(thread_id);
+export const ARCHIVED_THREAD_PURGE_DAYS = 730;
+/**
+ * Every table that stores rows keyed to one thread, in an order that clears
+ * child rows before their parents (note_embeddings via semantic_notes,
+ * voice_signatures via episodes). The thread_registry row itself is not on
+ * this list: purgeThread deletes it FIRST, so that a purge whose row was never
+ * marked (or was taken by a start) has touched none of these.
+ *
+ * THIS IS THE ONE HOME FOR THE LIST. A table added here is purged by both the
+ * single-thread delete and the daily sweep; a table missed here orphans its
+ * rows in both.
+ */
+const THREAD_DEPENDENT_DELETES = [
+    `DELETE FROM note_embeddings WHERE note_id IN (SELECT note_id FROM semantic_notes WHERE thread_id = ?)`,
+    `DELETE FROM temporal_narratives WHERE thread_id = ?`,
+    `DELETE FROM voice_signatures WHERE episode_id IN (SELECT episode_id FROM episodes WHERE thread_id = ?)`,
+    `DELETE FROM semantic_notes WHERE thread_id = ?`,
+    `DELETE FROM episodes WHERE thread_id = ?`,
+    `DELETE FROM sent_messages WHERE thread_id = ?`,
+    `DELETE FROM topic_registry WHERE thread_id = ?`,
+    // A worker's launch/death/release record. Purge runs only once no process can
+    // be alive for the thread (liveProcessRefusal), so nothing is left for the row
+    // to arbitrate. Dropping it also removes the worker from its card's
+    // prior-worker candidate set (listCardWorkers), which is correct for a worker
+    // proven gone.
+    `DELETE FROM worker_lifecycle WHERE thread_id = ?`,
+    // FYI lines queued for the thread's next turn, which it will never take.
+    `DELETE FROM passive_notices WHERE thread_id = ?`,
+];
+// ─── The row is the lock ─────────────────────────────────────────────────────
+//
+// A purge and a start of the SAME id race on one question: who owns the id right
+// now? The registry row answers it, and SQLite changes a row atomically. So both
+// sides take the row with one conditional UPDATE BEFORE any side effect, and the
+// loser sees `changes = 0` and touches nothing:
+//   - a purge marks the row (`purging_at`), then removes files, then deletes rows;
+//   - a start flips an archived row out of 'archived' before its first file write,
+//     and only while it is not marked.
+// This holds across an `await` on either side, and across two server processes
+// (a self-update overlap), which no in-memory lock can see. A crash mid-purge
+// leaves the mark, and the next sweep finishes the purge (selectThreadsMidPurge).
+// `purging_at` is a column, not a status, because a new status would mean
+// rebuilding the table's CHECK.
+/**
+ * Mark an archived row as being purged, answering the stamp written: the fence
+ * a finisher must still see to act. Empty means the purge lost: the row is not
+ * archived any more (a start claimed it), already marked, gone, or — when
+ * `archivedAt` is given — re-archived with a newer stamp than the one judged.
+ */
+export function markThreadPurging(db, threadId, archivedAt) {
+    const stamp = archivedAt === undefined ? "" : " AND archived_at = ?";
+    const params = archivedAt === undefined ? [] : [archivedAt];
+    const purgingAt = nowISO();
+    const changes = db
+        .prepare(`UPDATE thread_registry SET purging_at = ?
+       WHERE thread_id = ? AND status = 'archived' AND purging_at IS NULL${stamp}`)
+        .run(purgingAt, threadId, ...params).changes;
+    return changes > 0 ? Optional.of(purgingAt) : Optional.empty();
+}
+/** True while a purge owns the row (markThreadPurging): every door refuses it. */
+export function isThreadMarkedForPurge(db, threadId) {
+    return threadPurgeMark(db, threadId).has();
+}
+/** The mark a purge holds on the row now, or empty when none does. */
+export function threadPurgeMark(db, threadId) {
+    return Optional.fromNullable(db
+        .prepare(`SELECT purging_at FROM thread_registry WHERE thread_id = ? AND purging_at IS NOT NULL`)
+        // eslint-disable-next-line no-restricted-syntax -- SQLite returns undefined for an absent row
+        .get(threadId)).map((marked) => marked.purging_at);
+}
+/** The resting states a start takes a row out of: everything a process is not on. */
+const START_CLAIMABLE_STATUSES = ["archived", "exited", "created"];
+/**
+ * Every start of an existing id calls this BEFORE its first file write. It flips
+ * a resting row to `status` ('spawning' for a spawn, 'active' for a session that
+ * revives its thread), which is a state a purge refuses to mark. Synchronous and
+ * in one transaction, so the read, the flip and the note restore see the same row.
+ * A revived ARCHIVED row gets its archived notes back, exactly as unarchiveThread.
+ */
+export function claimThreadStart(db, threadId, status) {
+    return db.transaction(() => {
+        if (isThreadMarkedForPurge(db, threadId))
+            return { kind: "purging" };
+        const previous = Optional.fromNullable(getThread(db, threadId)).map((row) => row.status);
+        if (previous.orElse("") === "spawning")
+            return { kind: "starting" };
+        if (!previous.has() || !START_CLAIMABLE_STATUSES.includes(previous.get())) {
+            return { kind: "free" };
+        }
+        db.prepare(`UPDATE thread_registry SET status = ?, archived_at = NULL WHERE thread_id = ?`).run(status, threadId);
+        if (previous.get() === "archived") {
+            restoreNotesForThread(db, threadId, { includeUnknownLegacy: true });
         }
+        return { kind: "claimed", previous: previous.get(), claimedAs: status };
     })();
-    return rows.length;
+}
+/** Hand a claimed row back to the status it was taken from when its start failed. */
+export function releaseThreadStart(db, threadId, claim) {
+    if (claim.kind !== "claimed")
+        return;
+    db.prepare(`UPDATE thread_registry SET status = ?, archived_at = CASE WHEN ? = 'archived' THEN ? END
+     WHERE thread_id = ? AND status = ?`).run(claim.previous, claim.previous, nowISO(), threadId, claim.claimedAs);
+}
+/**
+ * Delete ONE thread's entire DB footprint — the registry row, then every table in
+ * THREAD_DEPENDENT_DELETES — in a single transaction. This is the LAST step of a
+ * purge: only a row still carrying the exact mark `purgingAt` this purge holds is
+ * deleted, so a row nobody marked, one a start took first, or a successor's row
+ * marked again matches nothing and the purge touches no dependent row. A row
+ * already gone means another purge finished it, and anything still keyed to the
+ * id is an orphan, which this cleans up. Returns true when this call deleted the
+ * registry row.
+ *
+ * DB only. On-disk per-thread artifacts are purgeThreadFiles' job
+ * (src/services/thread-purge.service.ts), and they are removed BEFORE this runs.
+ */
+export function purgeThread(db, threadId, purgingAt) {
+    const dependents = THREAD_DEPENDENT_DELETES.map((sql) => db.prepare(sql));
+    return db.transaction(() => {
+        const removed = db
+            .prepare(`DELETE FROM thread_registry WHERE thread_id = ? AND purging_at = ?`)
+            .run(threadId, purgingAt).changes > 0;
+        const rowLeft = db.prepare(`SELECT 1 FROM thread_registry WHERE thread_id = ?`).get(threadId);
+        if (rowLeft !== undefined)
+            return false;
+        for (const statement of dependents)
+            statement.run(threadId);
+        return removed;
+    })();
+}
+/** Rows a purge marked and has not finished, with each mark: a crash between
+ *  mark and row delete, a leftover that kept the rows, or a purge still awaiting
+ *  its file work. */
+export function selectThreadsMidPurge(db) {
+    return db
+        .prepare(`SELECT thread_id, purging_at FROM thread_registry WHERE purging_at IS NOT NULL`)
+        .all().map((row) => ({ threadId: row.thread_id, purgingAt: row.purging_at }));
+}
+/**
+ * Every archived thread that has an archive anchor — NOT a cutoff query, and
+ * nothing is deleted here. The age test lives in the sweep, in JavaScript, on
+ * parsed instants: `archived_at < cutoff` in SQL is a TEXT comparison, so a
+ * stamp that is not a canonical UTC ISO instant (`...-02:00`, a different
+ * precision) compares by characters rather than by time, and this is the
+ * predicate of an unattended delete.
+ *
+ * The sweep also has to gate each candidate on liveness — an async question no
+ * SQLite transaction can hold open — which is why selection and deletion are
+ * separate calls at all: `sweepOldArchivedThreads` in
+ * services/thread-purge.service.ts selects, validates, gates, marks, then purges.
+ *
+ * ANCHORED ON `archived_at`, NOT `last_active_at`. "730 days of grace after
+ * archiving" is what the window means, and last activity does not express it: a
+ * thread archived today whose last message was three years ago was eligible on
+ * the very next sweep. Every archived row has an anchor: updateThread derives it
+ * from the status, and migration 40 stamped the rows archived before it did.
+ */
+export function selectAnchoredArchivedThreads(db) {
+    const rows = db
+        .prepare(`SELECT thread_id, archived_at FROM thread_registry
+       WHERE status = 'archived' AND archived_at IS NOT NULL AND purging_at IS NULL`)
+        .all();
+    return rows.map((row) => ({ threadId: row.thread_id, archivedAt: row.archived_at }));
 }
 /**
  * Reset the daily session timestamp for a thread.
@@ -288,9 +581,16 @@ export function resetDailySession(db, threadId) {
     return result.changes > 0;
 }
 /**
- * Mark a thread's session as running (clean_shutdown = 0). Called at session
- * start; if the process dies before a graceful exit flips it back to 1, the
- * next resume sees 0 and knows the previous session was interrupted.
+ * Mark a thread's session as running (clean_shutdown = 0). Called from
+ * start_session, and the only write that clears the flag.
+ *
+ * The column now carries ONE meaning that code acts on: 0 = "the process
+ * currently attached to this thread reached start_session". spawn-common's
+ * registerSpawnedProcess sets it back to 1 for every new process, and the
+ * birth-death respawn net reads it to tell a thread that died before it ever
+ * registered from one that ran and then exited. (Its original job — letting the
+ * next resume notice an interrupted session — is handled by the memory
+ * briefing's self-judge prompt instead.)
  */
 export function markSessionRunning(db, threadId) {
     const result = db
@@ -303,8 +603,13 @@ export function markSessionRunning(db, threadId) {
  * alive at graceful exit (SIGTERM/SIGINT, maintenance restart), so a planned
  * server stop is not mistaken for a crash by the threads it takes down.
  * A thread that had already crashed lingers as status='active' but is absent
- * from aliveThreadIds, so its clean_shutdown stays 0 and the next resume
- * correctly detects the interruption. An empty list marks nothing.
+ * from aliveThreadIds, so its flag stays 0. An empty list marks nothing.
+ *
+ * In the {@link markSessionRunning} reading this says "no live process of ours
+ * is registered on that thread any more", which is true — the server is exiting.
+ * Agent children are detached and outlive it, so nothing re-reads the flag until
+ * they are re-adopted or respawned, and the respawn net's uptime window keeps a
+ * long-lived survivor out of scope.
  */
 export function markAliveThreadsCleanShutdown(db, aliveThreadIds) {
     if (aliveThreadIds.length === 0)
@@ -338,23 +643,174 @@ export function getExplicitTelegramTopicId(db, threadId) {
     return row?.telegram_topic_id ?? null;
 }
 /**
- * Backfill thread names from topic_registry for threads with empty/missing names.
- * Returns the number of threads updated.
+ * Record that `topicId` is gone by clearing the thread's stored pointer — only while
+ * the pointer still names `topicId`. A compare-and-clear, because every caller clears
+ * after an AWAITED delete: a pointer written in the meantime (the dashboard PATCH)
+ * names a topic that caller never deleted, and blanking it would hide that topic from
+ * the orphan sweep, which selects only stored pointers. Returns whether it cleared.
  */
-export function backfillMissingNames(db) {
-    const result = db
-        .prepare(`UPDATE thread_registry
-     SET name = (
-       SELECT tr.name FROM topic_registry tr
-       WHERE tr.thread_id = thread_registry.thread_id
-       LIMIT 1
-     )
-     WHERE (thread_registry.name IS NULL OR thread_registry.name = '')
-       AND EXISTS (
-         SELECT 1 FROM topic_registry tr
-         WHERE tr.thread_id = thread_registry.thread_id AND tr.name IS NOT NULL AND tr.name != ''
-       )`)
-        .run();
-    return result.changes;
+export function clearTelegramTopicIdIfStill(db, threadId, topicId) {
+    return (db
+        .prepare(`UPDATE thread_registry SET telegram_topic_id = NULL
+         WHERE thread_id = ? AND telegram_topic_id = ?`)
+        .run(threadId, topicId).changes > 0);
+}
+/**
+ * The topic number a DESTRUCTIVE teardown may aim at, stated once so no call site
+ * has to guess. Three arms, and the third is the point:
+ *
+ * 1. the explicit pointer when the row carries one — the only positive evidence of
+ *    which topic this thread owns;
+ * 2. else the thread id itself, but ONLY below {@link MINTED_THREAD_ID_FLOOR}: a
+ *    NULL column on a topic-numbered thread means the id IS the topic, which is
+ *    still true of every thread not born on the board's minting path;
+ * 3. else NOTHING. A minted id is not a topic number — the floor sits above int32
+ *    and Telegram topic ids are int32 — so falling back to it aims the delete at a
+ *    number no topic can have. Telegram answers TOPIC_ID_INVALID, which teardown
+ *    reads as "already gone", and the real topic is archived out of reach of every
+ *    sweep that looks for a stored pointer. Returning nothing is safe precisely
+ *    because no topic is recorded: there is no delete to retry later, so a caller
+ *    may treat the empty answer as a reached end state rather than a failure.
+ *
+ * Arm 2 becomes dead code once no below-floor worker remains.
+ */
+export function resolveDeletableTelegramTopicId(db, threadId) {
+    const explicit = Optional.fromNullable(getExplicitTelegramTopicId(db, threadId));
+    if (explicit.has())
+        return explicit;
+    return threadId < MINTED_THREAD_ID_FLOOR ? Optional.of(threadId) : Optional.empty();
+}
+/** The statuses in which a thread still OWNS its Telegram topic. Deliberately
+ *  expressed as the complement of the three terminal ones, so a status added to
+ *  the CHECK constraint later counts as live by default — the fail-safe
+ *  direction, since this predicate can only ever PREVENT a delete.
+ *
+ *  `exiting` is live, and that is the non-obvious member: `decommissionWorker`
+ *  ABORTS teardown and LEAVES the row `exiting` when the kill failed and the
+ *  agent is still running, so another actor must not delete that topic out from
+ *  under it. A row wedged in `exiting` cannot leak forever — the stale-row pass
+ *  of `cleanupExpiredWorkers` re-reaps any non-archived worker past its TTL.
+ *
+ *  `archived` is NOT live: the archived-worker orphan sweep exists precisely to
+ *  delete the topics of archived rows, so counting archived as live would turn
+ *  that sweep into a permanent no-op.
+ *
+ *  Two callers share this set, and they do NOT share the same answer.
+ *  `liveThreadClaimingTopic` below (may I destroy this topic) stops here: all
+ *  three terminal statuses are non-claimants. `threadOwningTopic` (who should
+ *  receive a message arriving in a topic) uses the set as its FIRST stage only,
+ *  then admits `exited` in a second, lower-priority one — because a thread that
+ *  may no longer DESTROY a topic can still be owed the messages arriving in it.
+ *  The fail-safe argument above is strict for the delete site; in routing's
+ *  stage 1 the same set decides only who WINS a contested topic, and the
+ *  membership rationale for stage 2 lives on `threadOwningTopic`. */
+const TERMINAL_TOPIC_STATUSES = ["archived", "expired", "exited"];
+/**
+ * The liveness predicate for a Telegram topic: which OTHER live thread, if any,
+ * still claims `topicId`.
+ *
+ * A Telegram topic is a shared, externally owned, DESTRUCTIVE resource, and this
+ * is the one question every delete site must ask first. Three separate paths
+ * (a stale `decommissionWorker` that continued past a failed transition, the
+ * periodic archived-worker orphan sweep, and the dashboard archive/hard-delete
+ * route) each resolved a topic and deleted it while a live thread still owned it,
+ * because each checked only its OWN row.
+ *
+ * Two arms, both load-bearing:
+ *  - `telegram_topic_id = ?` — the explicit claim.
+ *  - `telegram_topic_id IS NULL AND thread_id = ?` — the IMPLICIT claim.
+ *    `resolveTelegramTopicId` reads a NULL column as "my topic is my thread_id",
+ *    so a live row with a NULL column genuinely owns that topic number. Without
+ *    this arm the orphan sweep can delete a live thread's topic.
+ *
+ * `excludingThreadId` is the thread doing the deleting: it must never count
+ * itself as a claimant, or the ordinary case (a row tearing down the topic it
+ * alone holds) would stop deleting anything at all.
+ *
+ * Synchronous, like every other read here — which is what lets the dashboard's
+ * sync `handleDeleteThread` gate its fire-and-forget delete without becoming
+ * async and without moving its response.
+ */
+export function liveThreadClaimingTopic(db, topicId, excludingThreadId) {
+    const row = db
+        .prepare(`SELECT thread_id FROM thread_registry
+        WHERE thread_id != ?
+          AND status NOT IN (${TERMINAL_TOPIC_STATUSES.map(() => "?").join(", ")})
+          AND (telegram_topic_id = ? OR (telegram_topic_id IS NULL AND thread_id = ?))
+        LIMIT 1`)
+        .get(excludingThreadId, ...TERMINAL_TOPIC_STATUSES, topicId, topicId);
+    // `get` hands back `unknown`: absence is answered by `fromNullable`, which
+    // checks it at runtime, and the row SHAPE is asserted only inside `map`, where
+    // a row is known to be present.
+    return Optional.fromNullable(row).map((claimant) => claimant.thread_id);
+}
+/** One stage of `threadOwningTopic`: the first row its `WHERE` admits, or empty.
+ *  `get` hands back `unknown`: absence is answered by `fromNullable`, which checks
+ *  it at runtime, and the row SHAPE is asserted only inside `map`, where a row is
+ *  known to be present. */
+function topicClaimantWhere(db, where, binds) {
+    const row = db
+        .prepare(`SELECT thread_id FROM thread_registry WHERE ${where} LIMIT 1`)
+        .get(...binds);
+    return Optional.fromNullable(row).map((owner) => owner.thread_id);
+}
+/**
+ * The routing half of the ownership question: which thread, if any, should
+ * receive a message that arrived in `topicId`.
+ *
+ * TWO STAGES, and the priority between them is the point:
+ *   1. the LIVE owner — `TERMINAL_TOPIC_STATUSES` excluded, as the delete gate
+ *      does;
+ *   2. only when stage 1 is empty, the `exited` row that explicitly claims it.
+ *
+ * The stages are two SEQUENTIAL QUERIES with an early return, NOT an ordering
+ * inside one SELECT, and the distinction is worth stating because the paragraph
+ * below argues against an `ORDER BY`. The thing rejected there is an ARBITRARY
+ * tiebreak between rows no requirement ranks; this is a named priority between
+ * two different QUESTIONS, asked in order. A reader must not take one for the
+ * other.
+ *
+ * LIVE ALWAYS BEATS EXITED. That ordering is what stops a dead predecessor
+ * stealing a live successor's messages when both claim one topic — a state the
+ * dashboard PATCH route makes reachable today, and one that mint-once thread ids
+ * will GUARANTEE, since every respawn then has an exited row and a live row on
+ * the same topic by design.
+ *
+ * Stage 2 admits `exited` and only `exited`. `exited` → Active is a legal
+ * transition (`VALID_TRANSITIONS`), the dashboard permits starting an exited
+ * thread, and the wait poll loop evicts a parked agent only on `archived` /
+ * `expired` — so an exited row is one that may still be listening at its logical
+ * id, or be resumed to consume its backlog, while a message left at
+ * `<topicId>.jsonl` is read by nothing. `expired` stays OUT because `expired` →
+ * Active is structurally forbidden (Expired goes only to Archived) and the
+ * dashboard refuses to start it; `archived` stays OUT because an archived thread
+ * resumes by being REMAPPED onto a new topic while its old one is torn down by
+ * design.
+ *
+ * Only the EXPLICIT claim, in both stages. `liveThreadClaimingTopic`'s second arm
+ * (`telegram_topic_id IS NULL AND thread_id = ?`) is dead for routing: it can
+ * only ever answer `thread_id`, which equals `topicId`, which is already what the
+ * caller falls back to when this returns empty.
+ *
+ * No ORDER BY, matching the sibling. No LIFECYCLE writer can give two rows the
+ * same explicit `telegram_topic_id`: the column's one write seam is
+ * `updateThread`, every lifecycle caller writes either the row's own `thread_id`
+ * or an id Telegram just minted for that write, and the orphan sweep and
+ * `decommissionWorker` only clear.
+ * Minted ids are assumed unique within the configured chat — Telegram's
+ * numbering, not ours; unenforced here, and void if this registry is ever pointed
+ * at a different chat. The dashboard PATCH route (`buildThreadUpdates`) is the
+ * known exception: it writes any number the operator sends, so a two-claimant
+ * pair is operator-reachable, and WITHIN one stage this query then returns
+ * whichever row SQLite scans first — exactly the base behaviour. An ORDER BY
+ * would encode a winner no requirement names. The typed-open
+ * `ActivateThreadInput` / `TouchThreadInput` seam accepts a `telegramTopicId`
+ * too, with no production caller passing one today.
+ */
+export function threadOwningTopic(db, topicId) {
+    const liveOwner = topicClaimantWhere(db, `status NOT IN (${TERMINAL_TOPIC_STATUSES.map(() => "?").join(", ")}) AND telegram_topic_id = ?`, [...TERMINAL_TOPIC_STATUSES, topicId]);
+    if (liveOwner.has())
+        return liveOwner;
+    return topicClaimantWhere(db, `status = ? AND telegram_topic_id = ?`, ["exited", topicId]);
 }
 //# sourceMappingURL=thread-registry.js.map