@inflexa-ai/harness 0.44.0 → 0.45.1

package/dist/state/index.js

@@ -8,14 +8,14 @@
  */
 export { initCortexState } from "./init.js";
 export { upsertAnalysis, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
-export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, queryArtifactPage, countArtifactsByRuns, } from "./artifacts.js";
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, reconcileOrphanedRuns, ORPHANED_RUN_GRACE_MS, markRunCanceledIfActive, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, countRunsByAnalysis, queryRunsByThread, queryRunIdsByPlan, queryNewestPlanRun, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, clearSandboxRef, reconcileReapedSandbox } from "./active-sandboxes.js";
-export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
+export { insertPlan, upsertPlan, loadPlan, loadPlanRecord } from "./plans.js";
 export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, completeEmptyDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
-export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
+export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses, queryLatestRunsByAnalyses, queryRunProgressByRuns, queryRunsEndedSince, } from "./analyses-metrics.js";
 // Not per-entity: one analysis's whole Postgres footprint, reached from its id
 // alone, with the workflow ledger behind an injected seam.
 export { createAnalysisPurge } from "./purge-analysis.js";

package/dist/state/migrations/20261012120000_index_the_runs_by_start.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the runs of an analysis by their start time, thus the read of the
+ * newest run of each analysis of a list reads one index entry for each
+ * analysis, and its cost does not grow with the run history. The index on
+ * `analysis_id` alone stays: a drop is a separate decision.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexTheRunsByStart: Migration;

package/dist/state/migrations/20261012120000_index_the_runs_by_start.js

@@ -0,0 +1,12 @@
+/**
+ * Index the runs of an analysis by their start time, thus the read of the
+ * newest run of each analysis of a list reads one index entry for each
+ * analysis, and its cost does not grow with the run history. The index on
+ * `analysis_id` alone stays: a drop is a separate decision.
+ */
+import { sql } from "kysely";
+export const indexTheRunsByStart = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_analysis_started ON cortex_runs(analysis_id, started_at DESC, run_id DESC)`.execute(db);
+    },
+};

package/dist/state/migrations/20261013120000_index_the_ended_runs_and_the_recent_threads.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the runs by their completion time and the live threads by their update
+ * time, thus the reads over each analysis walk an index and do not sort the
+ * whole history. The thread index is partial on the live rows, the predicate of
+ * the read.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexTheEndedRunsAndTheRecentThreads: Migration;

package/dist/state/migrations/20261013120000_index_the_ended_runs_and_the_recent_threads.js

@@ -0,0 +1,13 @@
+/**
+ * Index the runs by their completion time and the live threads by their update
+ * time, thus the reads over each analysis walk an index and do not sort the
+ * whole history. The thread index is partial on the live rows, the predicate of
+ * the read.
+ */
+import { sql } from "kysely";
+export const indexTheEndedRunsAndTheRecentThreads = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_completed ON cortex_runs(completed_at DESC, run_id DESC)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_analysis_threads_recent ON cortex_analysis_threads(updated_at DESC, thread_id) WHERE deleted_at IS NULL`.execute(db);
+    },
+};

package/dist/state/migrations/20261013180000_narrow_the_active_run_index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Narrow the one-active-run index to the `running` status. A run that a host
+ * suspended is terminal, thus it no longer blocks a new run of its plan. A drop
+ * and a new index replace the index, because Postgres cannot change the
+ * predicate of an index.
+ */
+import type { Migration } from "kysely/migration";
+export declare const narrowTheActiveRunIndex: Migration;

package/dist/state/migrations/20261013180000_narrow_the_active_run_index.js

@@ -0,0 +1,13 @@
+/**
+ * Narrow the one-active-run index to the `running` status. A run that a host
+ * suspended is terminal, thus it no longer blocks a new run of its plan. A drop
+ * and a new index replace the index, because Postgres cannot change the
+ * predicate of an index.
+ */
+import { sql } from "kysely";
+export const narrowTheActiveRunIndex = {
+    async up(db) {
+        await sql `DROP INDEX IF EXISTS idx_cortex_runs_active_plan`.execute(db);
+        await sql `CREATE UNIQUE INDEX idx_cortex_runs_active_plan ON cortex_runs(analysis_id, plan_id) WHERE status = 'running'`.execute(db);
+    },
+};

package/dist/state/migrations/20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Index the plans by their parent, thus the read of the plan that replaced a
+ * plan, and the key check when a plan row goes away, read one index entry.
+ * Index the runs by their plan, thus the read of the run ids of a plan reads
+ * only the runs of that plan.
+ */
+import type { Migration } from "kysely/migration";
+export declare const indexThePlansByParentAndTheRunsByPlan: Migration;

package/dist/state/migrations/20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.js

@@ -0,0 +1,13 @@
+/**
+ * Index the plans by their parent, thus the read of the plan that replaced a
+ * plan, and the key check when a plan row goes away, read one index entry.
+ * Index the runs by their plan, thus the read of the run ids of a plan reads
+ * only the runs of that plan.
+ */
+import { sql } from "kysely";
+export const indexThePlansByParentAndTheRunsByPlan = {
+    async up(db) {
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_plans_parent ON cortex_plans(parent_plan_id)`.execute(db);
+        await sql `CREATE INDEX IF NOT EXISTS idx_cortex_runs_plan ON cortex_runs(analysis_id, plan_id, started_at DESC, run_id DESC)`.execute(db);
+    },
+};

package/dist/state/migrations/index.js

@@ -8,10 +8,18 @@
 import { baseline } from "./20260927120000_baseline.js";
 import { threadTitleSetByUser } from "./20260927180000_thread_title_set_by_user.js";
 import { dropActiveExecTracking } from "./20261005120000_drop_the_active_exec_tracking.js";
+import { indexTheRunsByStart } from "./20261012120000_index_the_runs_by_start.js";
+import { indexTheEndedRunsAndTheRecentThreads } from "./20261013120000_index_the_ended_runs_and_the_recent_threads.js";
+import { narrowTheActiveRunIndex } from "./20261013180000_narrow_the_active_run_index.js";
+import { indexThePlansByParentAndTheRunsByPlan } from "./20261014120000_index_the_plans_by_parent_and_the_runs_by_plan.js";
 export function cortexMigrations(logger) {
     return {
         "20260927120000_baseline": baseline(logger),
         "20260927180000_thread_title_set_by_user": threadTitleSetByUser,
         "20261005120000_drop_the_active_exec_tracking": dropActiveExecTracking,
+        "20261012120000_index_the_runs_by_start": indexTheRunsByStart,
+        "20261013120000_index_the_ended_runs_and_the_recent_threads": indexTheEndedRunsAndTheRecentThreads,
+        "20261013180000_narrow_the_active_run_index": narrowTheActiveRunIndex,
+        "20261014120000_index_the_plans_by_parent_and_the_runs_by_plan": indexThePlansByParentAndTheRunsByPlan,
     };
 }

package/dist/state/plans.d.ts

@@ -54,3 +54,24 @@ export declare function upsertPlan(pool: Querier, input: UpsertPlanInput): Resul
 export declare function loadPlan(pool: Querier, planId: string, opts: {
     analysisId: string;
 }): ResultAsync<unknown | null, DbError>;
+/** A stored plan with its lineage, as {@link loadPlanRecord} reads it. */
+export interface PlanRecord {
+    planId: string;
+    /** The stored document, as the store holds it. A reader parses it. */
+    plan: unknown;
+    parentPlanId: string | null;
+    /** The newest plan of the same analysis that names this plan as its parent. */
+    supersededBy: string | null;
+    createdAt: string;
+}
+/**
+ * Analysis-scoped read of one plan with its parent and the newest plan that
+ * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
+ * planId of a different analysis, as {@link loadPlan} does.
+ *
+ * `created_at` is ISO 8601 text, thus the text order is the time order; the plan
+ * id breaks a tie so that the answer is stable.
+ */
+export declare function loadPlanRecord(pool: Querier, planId: string, opts: {
+    analysisId: string;
+}): ResultAsync<PlanRecord | null, DbError>;

package/dist/state/plans.js

@@ -115,3 +115,28 @@ export function loadPlan(pool, planId, opts) {
         return result.rows[0]?.plan ?? null;
     });
 }
+/**
+ * Analysis-scoped read of one plan with its parent and the newest plan that
+ * replaced it, in one statement. Returns `ok(null)` for an unknown planId OR a
+ * planId of a different analysis, as {@link loadPlan} does.
+ *
+ * `created_at` is ISO 8601 text, thus the text order is the time order; the plan
+ * id breaks a tie so that the answer is stable.
+ */
+export function loadPlanRecord(pool, planId, opts) {
+    return tryQuery("plans.loadPlanRecord", async () => {
+        const result = await pool.query({
+            text: `SELECT p.plan, p.parent_plan_id, p.created_at,
+                     (SELECT c.plan_id FROM cortex_plans c
+                       WHERE c.parent_plan_id = p.plan_id AND c.analysis_id = p.analysis_id
+                       ORDER BY c.created_at DESC, c.plan_id DESC LIMIT 1) AS superseded_by
+                FROM cortex_plans p
+               WHERE p.plan_id = $1 AND p.analysis_id = $2`,
+            values: [planId, opts.analysisId],
+        });
+        const row = result.rows[0];
+        if (!row)
+            return null;
+        return { planId, plan: row.plan, parentPlanId: row.parent_plan_id, supersededBy: row.superseded_by, createdAt: row.created_at };
+    });
+}

package/dist/state/runs.d.ts

@@ -21,6 +21,8 @@ export interface InsertRunInput {
     planId?: string | null;
     mandateJti?: string | null;
     mandateExpiresAt?: string | null;
+    /** The start time as an ISO string. Without it, the row gets the clock of the host. */
+    startedAt?: string;
 }
 export interface RunReservation {
     readonly row: CortexRunRow;
@@ -64,6 +66,11 @@ export declare function reserveRunById(pool: Querier, input: InsertRunInput): Re
  * most one match.
  */
 export declare function queryActiveRun(pool: Querier, analysisId: string, planId: string | null): ResultAsync<CortexRunRow | null, DbError>;
+/** The optional text filter of the run reads. */
+export interface RunTextFilter {
+    /** A part of the run id or of the plan title, with no regard to case. Each character matches only itself. */
+    q?: string;
+}
 /**
  * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
  *
@@ -77,28 +84,86 @@ export declare function queryActiveRun(pool: Querier, analysisId: string, planId
  * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
  * finishes.
  *
- * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
- * suspended awaiting funds. Keep the two in step: a new non-terminal status added to one and not the
- * other makes a live run invisible to exactly one of its readers.
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means `running`. Keep the two
+ * in step: a new non-terminal status added to one and not the other makes a live run invisible to
+ * exactly one of its readers.
+ *
+ * With `q`, only the runs that the text filter selects are members.
+ */
+export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string, { q }?: RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
+/**
+ * How long a reserved run may wait for its workflow before {@link reconcileOrphanedRuns} fails it. A launch writes
+ * the workflow row seconds after the reservation, and the margin covers a slow authorization gate of a managed host.
  */
-export declare function queryActiveRunsByAnalysis(pool: Querier, analysisId: string): ResultAsync<CortexRunRow[], DbError>;
-export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<void, DbError>;
+export declare const ORPHANED_RUN_GRACE_MS: number;
+/**
+ * Fail each `running` run that started before the grace and that has no DBOS workflow row, and give the ids of
+ * the runs that it failed.
+ *
+ * A launch reserves the run row, then starts the workflow. A host that dies between the two, or a start that throws
+ * while the following status write also fails, leaves a `running` row that no workflow will ever settle. That row
+ * holds the active-plan slot, thus each later launch of the plan answers `started: false` for a run that never
+ * started. Recovery cannot help, because no workflow row exists to recover.
+ *
+ * Only a run with no workflow row at all is failed. A run whose workflow exists, also a terminal one, is the
+ * workflow's to settle: a failed mark could misname a run that completed. Call it after `DBOS.launch()`, thus a
+ * recovered workflow is visible to the predicate.
+ */
+export declare function reconcileOrphanedRuns(pool: Querier, opts?: {
+    now?: number;
+    graceMs?: number;
+}): ResultAsync<string[], DbError>;
+/**
+ * Write a status to a run row that is still `running`, and report whether the row changed. The first terminal write
+ * of a run wins: a row that already holds a terminal status keeps its status, its `completed_at`, and its error.
+ * The error text loses each NUL character, because Postgres rejects a NUL in text and the write must not fail for its own value.
+ */
+export declare function updateRunStatus(pool: Querier, runId: string, status: "running" | "completed" | "partial" | "failed" | "canceled" | "suspended_insufficient_funds", error?: string | null): ResultAsync<boolean, DbError>;
 /**
  * Conditionally transition an ACTIVE run to `canceled`, stamping `completed_at`
  * and recording `reason` in `error` (the same column `collectAndComplete`
  * stamps `external_cancel` into). Reports whether a row transitioned — false
  * means the run was already terminal (e.g. it completed concurrently with an
- * external cancel), and the caller MUST NOT fall back to `updateRunStatus`,
- * which would clobber that terminal status. The guarded set is the active set
- * `queryActiveRun` deduplicates on.
+ * external cancel). The guarded set is the active set `queryActiveRun`
+ * deduplicates on.
  */
 export declare function markRunCanceledIfActive(pool: Querier, runId: string, reason: string): ResultAsync<boolean, DbError>;
 export declare function promoteFailedToPartial(pool: Querier, runId: string): ResultAsync<boolean, DbError>;
 export declare function queryRun(pool: Querier, runId: string): ResultAsync<CortexRunRow | null, DbError>;
-export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, { limit, offset }?: {
+/**
+ * One window of the runs of an analysis, newest start first. With `q`, the window holds only the runs that the text
+ * filter selects: the filter applies before `limit` and `offset`, and it does not change the order.
+ */
+export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, { limit, offset, q }?: {
     limit?: number;
     offset?: number;
-}): ResultAsync<CortexRunRow[], DbError>;
+} & RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
+/**
+ * The count of the runs of an analysis, in one statement. With `q`, the count holds only the runs that the text filter
+ * selects, thus it agrees with the windows of {@link queryRunsByAnalysis} for the same `q`.
+ */
+export declare function countRunsByAnalysis(pool: Querier, analysisId: string, { q }?: RunTextFilter): ResultAsync<number, DbError>;
+/**
+ * The run ids of one plan of one analysis, newest start first, at most `limit`.
+ * The run id breaks a tie of start times, highest first. A plan with no run gives
+ * an empty list.
+ */
+export declare function queryRunIdsByPlan(pool: Querier, opts: {
+    analysisId: string;
+    planId: string;
+    limit: number;
+}): ResultAsync<string[], DbError>;
+/**
+ * The newest run of one plan of one analysis, or `null` for a plan with no run. The order is the one of
+ * {@link queryRunIdsByPlan}: the latest start first, and the highest run id on a tie of start times.
+ */
+export declare function queryNewestPlanRun(pool: Querier, opts: {
+    analysisId: string;
+    planId: string;
+}): ResultAsync<{
+    runId: string;
+    startedAt: string;
+} | null, DbError>;
 /**
  * Read the analysis's non-terminal run activity without coupling it to a
  * conversation thread. The total is counted before the detail limit so a
@@ -106,8 +171,7 @@ export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, {
  */
 export declare function queryNonTerminalRunsByAnalysis(pool: Querier, analysisId: string, limit?: number): ResultAsync<RunPage, DbError>;
 /**
- * Read one stable inspection page: running first, then suspended, then
- * terminal history. This is deliberately separate from
+ * Read one stable inspection page: running first, then each other run. This is deliberately separate from
  * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
  * contract.
  */
@@ -115,10 +179,11 @@ export declare function queryRunsForInspection(pool: Querier, analysisId: string
     limit?: number;
     offset?: number;
 }): ResultAsync<RunPage, DbError>;
-export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset }?: {
+/** The runs of one thread of an analysis, newest start first. With `q`, the text filter applies before the window. */
+export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset, q }?: {
     limit?: number;
     offset?: number;
-}): ResultAsync<CortexRunRow[], DbError>;
+} & RunTextFilter): ResultAsync<CortexRunRow[], DbError>;
 /**
  * Persist the run mandate jti + expiry for a run. oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
  * Called by `authorizeForRun` after a successful mint so the cancel

package/dist/state/runs.js

@@ -9,6 +9,7 @@
  * `DbError`. Every other write maps SQLSTATE 23505/23503/23502/23514 to
  * `err(constraint_violation)` via `tryMutation`.
  */
+import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 export class RunIdentityCollisionError extends Error {
     runId;
@@ -44,7 +45,7 @@ export class RunDedupCollisionError extends Error {
  * the err channel as a `DbError`.
  */
 export function insertRun(pool, input) {
-    const now = new Date().toISOString();
+    const now = input.startedAt ?? new Date().toISOString();
     return tryMutation("runs.insertRun", async () => {
         await pool.query({
             text: `INSERT INTO cortex_runs
@@ -75,7 +76,7 @@ export function insertRun(pool, input) {
 }
 /** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
 export function reserveRunById(pool, input) {
-    const now = new Date().toISOString();
+    const now = input.startedAt ?? new Date().toISOString();
     return tryMutation("runs.reserveRunById", async () => {
         const result = await pool.query({
             text: `INSERT INTO cortex_runs
@@ -132,13 +133,27 @@ export function queryActiveRun(pool, analysisId, planId) {
             FROM cortex_runs
             WHERE analysis_id = $1
               AND plan_id IS NOT DISTINCT FROM $2
-              AND status IN ('running','suspended_insufficient_funds')`,
+              AND status = 'running'`,
             values: [analysisId, planId],
         });
         const row = result.rows[0];
         return row ? mapRunRow(row) : null;
     });
 }
+/**
+ * The SQL condition of the text filter `q` for the bound placeholder `placeholder`. A run matches when its id holds the
+ * text, or when the `title` of the plan of the same analysis holds it. `strpos` is the test, because `LIKE` would turn
+ * `%` and `_` of the input into wildcards. The `analysis_id` condition keeps the plan of a different analysis out, the
+ * same scope as `loadPlan`.
+ */
+function runTextCondition(placeholder) {
+    return `(strpos(lower(run_id), lower(${placeholder}::text)) > 0
+              OR EXISTS (SELECT 1 FROM cortex_plans p
+                         WHERE p.plan_id = cortex_runs.plan_id
+                           AND p.analysis_id = cortex_runs.analysis_id
+                           AND jsonb_typeof(p.plan -> 'title') = 'string'
+                           AND strpos(lower(p.plan ->> 'title'), lower(${placeholder}::text)) > 0))`;
+}
 /**
  * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
  *
@@ -152,35 +167,82 @@ export function queryActiveRun(pool, analysisId, planId) {
  * analysis's live concurrency, not by its history, and a run leaves the set permanently when it
  * finishes.
  *
- * The status set is the one {@link queryActiveRun} uses — non-terminal means still running, or
- * suspended awaiting funds. Keep the two in step: a new non-terminal status added to one and not the
- * other makes a live run invisible to exactly one of its readers.
+ * The status set is the one {@link queryActiveRun} uses — non-terminal means `running`. Keep the two
+ * in step: a new non-terminal status added to one and not the other makes a live run invisible to
+ * exactly one of its readers.
+ *
+ * With `q`, only the runs that the text filter selects are members.
  */
-export function queryActiveRunsByAnalysis(pool, analysisId) {
+export function queryActiveRunsByAnalysis(pool, analysisId, { q } = {}) {
     return tryQuery("runs.queryActiveRunsByAnalysis", async () => {
+        const values = [analysisId];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')
+              AND status = 'running'
+              ${text}
             ORDER BY started_at DESC`,
-            values: [analysisId],
+            values,
         });
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * How long a reserved run may wait for its workflow before {@link reconcileOrphanedRuns} fails it. A launch writes
+ * the workflow row seconds after the reservation, and the margin covers a slow authorization gate of a managed host.
+ */
+export const ORPHANED_RUN_GRACE_MS = 5 * 60 * 1000;
+/**
+ * Fail each `running` run that started before the grace and that has no DBOS workflow row, and give the ids of
+ * the runs that it failed.
+ *
+ * A launch reserves the run row, then starts the workflow. A host that dies between the two, or a start that throws
+ * while the following status write also fails, leaves a `running` row that no workflow will ever settle. That row
+ * holds the active-plan slot, thus each later launch of the plan answers `started: false` for a run that never
+ * started. Recovery cannot help, because no workflow row exists to recover.
+ *
+ * Only a run with no workflow row at all is failed. A run whose workflow exists, also a terminal one, is the
+ * workflow's to settle: a failed mark could misname a run that completed. Call it after `DBOS.launch()`, thus a
+ * recovered workflow is visible to the predicate.
+ */
+export function reconcileOrphanedRuns(pool, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const before = new Date(now - (opts.graceMs ?? ORPHANED_RUN_GRACE_MS)).toISOString();
+    return tryMutation("runs.reconcileOrphanedRuns", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_runs r
+            SET status = 'failed',
+                error = 'The workflow of the run never started.',
+                completed_at = $1
+            WHERE r.status = 'running'
+              AND r.started_at < $2
+              AND NOT EXISTS (SELECT 1 FROM dbos.workflow_status ws WHERE ws.workflow_uuid = r.run_id)
+            RETURNING r.run_id`,
+            values: [new Date(now).toISOString(), before],
+        });
+        return result.rows.map((row) => row.run_id);
+    });
+}
+/**
+ * Write a status to a run row that is still `running`, and report whether the row changed. The first terminal write
+ * of a run wins: a row that already holds a terminal status keeps its status, its `completed_at`, and its error.
+ * The error text loses each NUL character, because Postgres rejects a NUL in text and the write must not fail for its own value.
+ */
 export function updateRunStatus(pool, runId, status, error) {
     const now = new Date().toISOString();
-    const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled";
+    const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled" || status === "suspended_insufficient_funds";
     return tryMutation("runs.updateRunStatus", async () => {
-        await pool.query({
+        const result = await pool.query({
             text: `UPDATE cortex_runs
             SET status = $1, completed_at = $2, error = $3
-            WHERE run_id = $4`,
-            values: [status, isTerminal ? now : null, error ?? null, runId],
+            WHERE run_id = $4 AND status = 'running'`,
+            values: [status, isTerminal ? now : null, error === undefined || error === null ? null : stripNulCharacters(error), runId],
         });
+        return (result.rowCount ?? 0) > 0;
     });
 }
 /**
@@ -188,9 +250,8 @@ export function updateRunStatus(pool, runId, status, error) {
  * and recording `reason` in `error` (the same column `collectAndComplete`
  * stamps `external_cancel` into). Reports whether a row transitioned — false
  * means the run was already terminal (e.g. it completed concurrently with an
- * external cancel), and the caller MUST NOT fall back to `updateRunStatus`,
- * which would clobber that terminal status. The guarded set is the active set
- * `queryActiveRun` deduplicates on.
+ * external cancel). The guarded set is the active set `queryActiveRun`
+ * deduplicates on.
  */
 export function markRunCanceledIfActive(pool, runId, reason) {
     const now = new Date().toISOString();
@@ -198,7 +259,7 @@ export function markRunCanceledIfActive(pool, runId, reason) {
         const result = await pool.query({
             text: `UPDATE cortex_runs
             SET status = 'canceled', completed_at = $2, error = $3
-            WHERE run_id = $1 AND status IN ('running','suspended_insufficient_funds')`,
+            WHERE run_id = $1 AND status = 'running'`,
             values: [runId, now, reason],
         });
         return (result.rowCount ?? 0) > 0;
@@ -228,20 +289,79 @@ export function queryRun(pool, runId) {
         return row ? mapRunRow(row) : null;
     });
 }
-export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 } = {}) {
+/**
+ * One window of the runs of an analysis, newest start first. With `q`, the window holds only the runs that the text
+ * filter selects: the filter applies before `limit` and `offset`, and it does not change the order.
+ */
+export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0, q } = {}) {
     return tryQuery("runs.queryRunsByAnalysis", async () => {
+        const values = [analysisId, limit, offset];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1
+              ${text}
             ORDER BY started_at DESC LIMIT $2 OFFSET $3`,
-            values: [analysisId, limit, offset],
+            values,
         });
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * The count of the runs of an analysis, in one statement. With `q`, the count holds only the runs that the text filter
+ * selects, thus it agrees with the windows of {@link queryRunsByAnalysis} for the same `q`.
+ */
+export function countRunsByAnalysis(pool, analysisId, { q } = {}) {
+    return tryQuery("runs.countRunsByAnalysis", async () => {
+        const values = [analysisId];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
+        const result = await pool.query({
+            text: `SELECT COUNT(*)::int AS total
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              ${text}`,
+            values,
+        });
+        return Number(result.rows[0]?.total ?? 0);
+    });
+}
+/**
+ * The run ids of one plan of one analysis, newest start first, at most `limit`.
+ * The run id breaks a tie of start times, highest first. A plan with no run gives
+ * an empty list.
+ */
+export function queryRunIdsByPlan(pool, opts) {
+    return tryQuery("runs.queryRunIdsByPlan", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id FROM cortex_runs
+            WHERE analysis_id = $1 AND plan_id = $2
+            ORDER BY started_at DESC, run_id DESC
+            LIMIT $3`,
+            values: [opts.analysisId, opts.planId, opts.limit],
+        });
+        return result.rows.map((row) => row.run_id);
+    });
+}
+/**
+ * The newest run of one plan of one analysis, or `null` for a plan with no run. The order is the one of
+ * {@link queryRunIdsByPlan}: the latest start first, and the highest run id on a tie of start times.
+ */
+export function queryNewestPlanRun(pool, opts) {
+    return tryQuery("runs.queryNewestPlanRun", async () => {
+        const result = await pool.query({
+            text: `SELECT run_id, started_at FROM cortex_runs
+            WHERE analysis_id = $1 AND plan_id = $2
+            ORDER BY started_at DESC, run_id DESC
+            LIMIT 1`,
+            values: [opts.analysisId, opts.planId],
+        });
+        const row = result.rows[0];
+        return row ? { runId: row.run_id, startedAt: row.started_at } : null;
+    });
+}
 /**
  * Read the analysis's non-terminal run activity without coupling it to a
  * conversation thread. The total is counted before the detail limit so a
@@ -253,7 +373,7 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
             text: `SELECT COUNT(*)::int AS total
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')`,
+              AND status = 'running'`,
             values: [analysisId],
         });
         const rowsResult = await pool.query({
@@ -262,13 +382,8 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
                    mandate_jti, mandate_expires_at, plan_id
             FROM cortex_runs
             WHERE analysis_id = $1
-              AND status IN ('running','suspended_insufficient_funds')
-            ORDER BY CASE status
-                         WHEN 'running' THEN 0
-                         WHEN 'suspended_insufficient_funds' THEN 1
-                         ELSE 2
-                     END,
-                     started_at DESC,
+              AND status = 'running'
+            ORDER BY started_at DESC,
                      run_id DESC
             LIMIT $2`,
             values: [analysisId, limit],
@@ -280,8 +395,7 @@ export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
     });
 }
 /**
- * Read one stable inspection page: running first, then suspended, then
- * terminal history. This is deliberately separate from
+ * Read one stable inspection page: running first, then each other run. This is deliberately separate from
  * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
  * contract.
  */
@@ -299,8 +413,7 @@ export function queryRunsForInspection(pool, analysisId, { limit = 50, offset =
             WHERE analysis_id = $1
             ORDER BY CASE status
                          WHEN 'running' THEN 0
-                         WHEN 'suspended_insufficient_funds' THEN 1
-                         ELSE 2
+                         ELSE 1
                      END,
                      started_at DESC,
                      run_id DESC
@@ -313,16 +426,20 @@ export function queryRunsForInspection(pool, analysisId, { limit = 50, offset =
         };
     });
 }
-export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0 } = {}) {
+/** The runs of one thread of an analysis, newest start first. With `q`, the text filter applies before the window. */
+export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0, q } = {}) {
     return tryQuery("runs.queryRunsByThread", async () => {
+        const values = [analysisId, threadId, limit, offset];
+        const text = q === undefined ? "" : `AND ${runTextCondition(`$${values.push(q)}`)}`;
         const result = await pool.query({
             text: `SELECT run_id, analysis_id, thread_id, workflow_name,
                    status, started_at, completed_at, error, synthesis_status, synthesis_reason, parts,
                    mandate_jti, mandate_expires_at, plan_id -- oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
             FROM cortex_runs
             WHERE analysis_id = $1 AND thread_id = $2
+              ${text}
             ORDER BY started_at DESC LIMIT $3 OFFSET $4`,
-            values: [analysisId, threadId, limit, offset],
+            values,
         });
         return result.rows.map(mapRunRow);
     });