@inflexa-ai/harness 0.12.0 → 0.14.0

package/dist/state/data-profile.js

@@ -38,21 +38,31 @@ export function tryStartDataProfile(pool, analysisId) {
     return tryMutation("dataProfile.tryStartDataProfile", async () => {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
-            SET data_profile_status = 'running', data_profile_started_at = $1
+            SET data_profile_status = 'running', data_profile_started_at = $1,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND (data_profile_status = 'pending' OR data_profile_status IS NULL) AND ${SEEDED}`,
             values: [now, analysisId],
         });
         return (result.rowCount ?? 0) > 0;
     });
 }
-/** Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}. */
+/**
+ * Claim a `failed` row back into `running` (the deliberate-retry route). Carries {@link SEEDED}.
+ *
+ * Clears `data_profile_workflow_id`, because the claim IS the moment a new attempt takes the row
+ * and the prior attempt's workflow is finished. Left in place it would leave the row `running`
+ * while naming a stream that has already drained, so a consumer would subscribe and observe
+ * nothing without knowing why; NULL says "not addressable yet", which is exactly true until the
+ * new body records its own id (see {@link recordDataProfileWorkflowId}).
+ */
 export function tryRetryDataProfile(pool, analysisId) {
     const now = new Date().toISOString();
     return tryMutation("dataProfile.tryRetryDataProfile", async () => {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'running', data_profile_started_at = $1,
-                data_profile_error = NULL, data_profile_completed_at = NULL
+                data_profile_error = NULL, data_profile_completed_at = NULL,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND data_profile_status = 'failed' AND ${SEEDED}`,
             values: [now, analysisId],
         });
@@ -63,6 +73,11 @@ export function tryRetryDataProfile(pool, analysisId) {
  * Claim a `completed` row back into `running` (the re-profile route). `data_profile_result`
  * is deliberately preserved so a consumer can keep serving the prior profile while the new
  * one runs. Carries {@link SEEDED}.
+ *
+ * `data_profile_workflow_id` is NOT preserved alongside it, and the asymmetry is the point: the
+ * result is CONTENT that stays valid until replaced, while the id is a POINTER to a live stream
+ * whose workflow is now finished. Keeping it would leave the row `running` while naming a drained
+ * stream — see {@link tryRetryDataProfile} for the same reasoning.
  */
 export function tryRerunDataProfile(pool, analysisId) {
     const now = new Date().toISOString();
@@ -70,13 +85,56 @@ export function tryRerunDataProfile(pool, analysisId) {
         const result = await pool.query({
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = 'running', data_profile_started_at = $1,
-                data_profile_error = NULL, data_profile_completed_at = NULL
+                data_profile_error = NULL, data_profile_completed_at = NULL,
+                data_profile_workflow_id = NULL
             WHERE analysis_id = $2 AND data_profile_status = 'completed' AND ${SEEDED}`,
             values: [now, analysisId],
         });
         return (result.rowCount ?? 0) > 0;
     });
 }
+/**
+ * Record the DBOS workflow id of the attempt that owns a claimed-`running` row, so a
+ * consumer resolves which durable event stream carries this profile's activity from the
+ * ledger row alone — no durability-engine query, no id reconstructed from the workflow-id
+ * string format. The workflow BODY calls this, never the trigger: the claim CAS runs
+ * before the workflow id is minted, so only the body can report the id of the attempt
+ * that actually started.
+ *
+ * `AND data_profile_status = 'running'` buys exactly one thing: a write that lands late
+ * cannot stamp a row that has already settled, which would otherwise point a consumer at
+ * a workflow for a profile that is already finished. What it does NOT buy is
+ * disambiguation between two attempts that each believe they are the running one — the
+ * stale-expiry claim admits precisely that, since a row whose `data_profile_started_at`
+ * has aged past the timeout can be claimed by a second attempt while the first body is
+ * still alive but has not completed its first step, and that first step then overwrites
+ * the second's id.
+ *
+ * That residue is deliberately left open rather than closed. Its worst outcome is already
+ * a specified-normal state: a consumer subscribed to a superseded workflow reads a stream
+ * that has already drained, so it observes no activity — indistinguishable from "running,
+ * nothing reported yet". A missing activity line for one profile is acceptable; a wrong
+ * one would not be. And closing it costs more than it buys: either the three claim
+ * functions widen their `Result<boolean>` returns to carry the id — their callers branch
+ * on truthiness (`if (!retried)`), so an object return makes every such branch
+ * always-taken, a silent behaviour change in the embedder's recovery path — or the
+ * embedder mints the workflow ids, putting a harness-internal construction in a
+ * consumer's hands.
+ *
+ * `ok(true)` when this call stamped the row; `ok(false)` when the CAS refused it — a
+ * normal in-band outcome, not an error.
+ */
+export function recordDataProfileWorkflowId(pool, analysisId, workflowId) {
+    return tryMutation("dataProfile.recordDataProfileWorkflowId", async () => {
+        const result = await pool.query({
+            text: `UPDATE cortex_analysis_state
+            SET data_profile_workflow_id = $1
+            WHERE analysis_id = $2 AND data_profile_status = 'running'`,
+            values: [workflowId, analysisId],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.
@@ -213,7 +271,8 @@ export function clearDataProfile(pool, analysisId) {
             text: `UPDATE cortex_analysis_state
             SET data_profile_status = NULL, data_profile_error = NULL,
                 data_profile_started_at = NULL, data_profile_completed_at = NULL,
-                data_profile_result = NULL, seed_input_file_ids = NULL
+                data_profile_result = NULL, data_profile_workflow_id = NULL,
+                seed_input_file_ids = NULL
             WHERE analysis_id = $1 AND data_profile_status IS DISTINCT FROM 'running'`,
             values: [analysisId],
         });
@@ -242,7 +301,7 @@ export function loadDataProfileStatus(pool, analysisId) {
         const result = await pool.query({
             text: `SELECT data_profile_status, data_profile_error,
                    data_profile_started_at, data_profile_completed_at,
-                   data_profile_result, seed_input_file_ids
+                   data_profile_result, data_profile_workflow_id, seed_input_file_ids
             FROM cortex_analysis_state WHERE analysis_id = $1`,
             values: [analysisId],
         });
@@ -255,6 +314,7 @@ export function loadDataProfileStatus(pool, analysisId) {
             startedAt: row.data_profile_started_at ?? null,
             completedAt: row.data_profile_completed_at ?? null,
             result: row.data_profile_result ?? null,
+            workflowId: row.data_profile_workflow_id ?? null,
             seedInputFileIds: row.seed_input_file_ids ?? null,
         };
     });

package/dist/state/index.d.ts

@@ -11,16 +11,16 @@ export type { Querier } from "./db.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
 export type { RegisterArtifactInput, InputArtifactMeta, StepArtifactRef } from "./artifacts.js";
-export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
-export type { InsertRunInput } from "./runs.js";
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export type { InsertStepExecutionInput, SeedStepExecutionRow, UpdateStepExecutionInput } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
 export type { ActiveSandboxRow } from "./active-sandboxes.js";
-export { insertPlan, loadPlan } from "./plans.js";
-export type { InsertPlanInput } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
+export type { InsertPlanInput, UpsertPlanInput } from "./plans.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export type { DataProfileStatus, DataProfileResult, DataProfileInputFile, DataProfileFile, DataProfileQualityAssessment } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";

package/dist/state/index.js

@@ -9,12 +9,12 @@
 export { initCortexState } from "./init.js";
 export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
 export { upsertArtifact, upsertArtifacts, queryInputArtifacts, queryStepArtifactPaths, queryUnsyncedStepArtifacts, updateArtifactId, updateFileIds, countArtifactsForRun, } from "./artifacts.js";
-export { insertRun, RunDedupCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
-setRunSynthesisOutcome, queryRun, queryActiveRun, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
+export { insertRun, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+setRunSynthesisOutcome, queryRun, queryActiveRun, queryNonTerminalRunsByAnalysis, queryRunsForInspection, queryRunsByAnalysis, queryRunsByThread, } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";
-export { insertPlan, loadPlan } from "./plans.js";
-export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, } from "./data-profile.js";
+export { insertPlan, upsertPlan, loadPlan } from "./plans.js";
+export { tryStartDataProfile, tryRetryDataProfile, tryRerunDataProfile, completeDataProfile, failDataProfile, expireStaleDataProfile, reconcileOrphanedDataProfile, clearDataProfile, loadDataProfileStatus, loadSeedInputFileIds, recordDataProfileWorkflowId, } from "./data-profile.js";
 export { queryRunCountsByAnalyses, queryThreadCountsByAnalyses, queryDataProfileStatusByAnalyses } from "./analyses-metrics.js";
 export { AnalysisStateRowSchema, ArtifactRole, ArtifactRowSchema, RunStatus, StepExecutionStatus, SynthesisStatus, CortexRunRowSchema, StepExecutionRowSchema, CortexPlanRowSchema, } from "./schema.js";
 export { insertAssessment, updateProgress, setDossier, markFailed, getAssessment, listAssessmentsByOrg, softDeleteAssessment, TargetAssessmentStatusSchema, TargetAssessmentErrorSchema, TargetAssessmentRowSchema, } from "./target-assessments.js";

package/dist/state/init.js

@@ -27,10 +27,22 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_state (
   data_profile_started_at   TEXT,
   data_profile_completed_at TEXT,
   data_profile_result       JSONB,
+  data_profile_workflow_id  TEXT,
   created_at                TEXT NOT NULL,
   updated_at                TEXT NOT NULL
 );
 
+-- DBOS workflow id of the profile attempt that owns the row — what a consumer
+-- subscribes to in order to observe that profile's activity. Written by the
+-- workflow body, not the trigger: the ledger claim happens before the workflow id
+-- is minted, so only the body knows the id of the attempt that actually started.
+-- Nullable, and absence is a normal state rather than a defect, with two ordinary
+-- causes: a row claimed whose body has not yet recorded its id, and a row written
+-- before this column existed. Both mean "this profile's stream is not
+-- addressable", which is true in each case — hence no backfill.
+ALTER TABLE cortex_analysis_state
+  ADD COLUMN IF NOT EXISTS data_profile_workflow_id TEXT;
+
 -- File registry — artifact_id (provenance) + file_id (S3), cross-run.
 CREATE TABLE IF NOT EXISTS cortex_artifacts (
   analysis_id   TEXT NOT NULL,
@@ -207,12 +219,20 @@ CREATE INDEX IF NOT EXISTS idx_cortex_regulatory_chunks_metadata
 -- workflow and sandbox agent loops use the DBOS step cache, never this
 -- table (see the harness-thread-store spec). The (thread_id, seq) primary key already serves
 -- (thread_id, seq DESC) reads, so no separate index is needed.
+--
+-- message_envelope is JSON, not JSONB, and must stay that way. JSONB stores a
+-- re-sorted parse tree rather than the document it was given, so a tool call's
+-- input — and every other free-form payload, which has no schema to be
+-- normalized back against on read — comes back key-reordered. Those bytes are
+-- re-sent to the provider on the next turn, where a reordered prefix misses the
+-- prompt cache. JSON stores the text verbatim. Nothing indexes this column, and
+-- the JSON operators retractLastTurn uses work the same on either type.
 CREATE TABLE IF NOT EXISTS messages (
   thread_id     TEXT NOT NULL,
   seq           BIGINT NOT NULL,
   role          TEXT,
   content_jsonb JSONB,
-  message_envelope JSONB,
+  message_envelope JSON,
   tokens        INTEGER NOT NULL,
   created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   PRIMARY KEY (thread_id, seq)
@@ -411,7 +431,22 @@ export async function initCortexState(pool, injected) {
                 // carry the NOT NULL floor, which would reject a clear. Idempotent:
                 // dropping an absent NOT NULL no-ops, so this is a no-op on fresh DBs.
                 "ALTER TABLE cortex_analysis_state ALTER COLUMN data_profile_status DROP NOT NULL",
-                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSONB",
+                "ALTER TABLE messages ADD COLUMN IF NOT EXISTS message_envelope JSON",
+                // Demote an existing JSONB envelope column to JSON (see the CREATE
+                // TABLE comment). Type-guarded because ALTER ... TYPE rewrites the
+                // whole table and this runs at every boot; scoped to
+                // current_schema() so parallel test schemas never see each other.
+                // Rows already written as JSONB carry over as they stand — their
+                // original key order is not recoverable.
+                `DO $$ BEGIN
+                  IF EXISTS (
+                    SELECT 1 FROM information_schema.columns
+                    WHERE table_schema = current_schema() AND table_name = 'messages'
+                      AND column_name = 'message_envelope' AND data_type = 'jsonb'
+                  ) THEN
+                    ALTER TABLE messages ALTER COLUMN message_envelope TYPE JSON USING message_envelope::text::json;
+                  END IF;
+                END $$`,
                 // Grant key an 'always' records the standing grant under. Nullable
                 // and unbackfilled: every new row writes it (command when absent), and
                 // orphaned legacy pending rows are swept to 'expired' before any answer

package/dist/state/plans.js

@@ -6,7 +6,7 @@ import { randomUUID } from "node:crypto";
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 /**
  * `cortex_plans.plan_id` shape contract — `pln-` followed by 8 lowercase hex
- * chars. The chat trigger (`tools/execute-plan.ts`) enforces the same regex on
+ * chars. The chat trigger (`tools/execute-analysis.ts`) enforces the same regex on
  * its tool input; `upsertPlan` re-asserts it because it accepts a caller-derived
  * id rather than minting one.
  */

package/dist/state/runs.d.ts

@@ -22,6 +22,19 @@ export interface InsertRunInput {
     mandateJti?: string | null;
     mandateExpiresAt?: string | null;
 }
+export interface RunReservation {
+    readonly row: CortexRunRow;
+    readonly inserted: boolean;
+}
+/** Bounded run rows paired with the true count before limit/offset. */
+export interface RunPage {
+    readonly runs: CortexRunRow[];
+    readonly total: number;
+}
+export declare class RunIdentityCollisionError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
 /**
  * Raised when `insertRun` collides with the partial-unique index
  * `idx_cortex_runs_active_plan` — i.e., an active run already exists for
@@ -43,12 +56,32 @@ export declare class RunDedupCollisionError extends Error {
  * the err channel as a `DbError`.
  */
 export declare function insertRun(pool: Querier, input: InsertRunInput): ResultAsync<void, DbError>;
+/** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
+export declare function reserveRunById(pool: Querier, input: InsertRunInput): ResultAsync<RunReservation, DbError>;
 /**
  * Recover the active run row for `(analysisId, planId)` after `insertRun`
  * raises `RunDedupCollisionError`. The partial-unique index guarantees at
  * most one match.
  */
 export declare function queryActiveRun(pool: Querier, analysisId: string, planId: string | null): ResultAsync<CortexRunRow | null, DbError>;
+/**
+ * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
+ *
+ * The counterpart to {@link queryRunsByAnalysis}, which answers "the newest N runs" — a windowed
+ * question, and the wrong one for a host driving live surfaces. Ordering by `started_at DESC` and
+ * capping means the run most worth watching is the first to fall out: a long analysis still going
+ * while ten short ones start and finish after it leaves the window entirely, so a host reading only
+ * that window loses its progress AND never learns it terminated.
+ *
+ * Unbounded is safe here in a way it is not for the general listing: this result is capped by the
+ * 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.
+ */
+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 function promoteFailedToPartial(pool: Querier, runId: string): ResultAsync<boolean, DbError>;
 export declare function queryRun(pool: Querier, runId: string): ResultAsync<CortexRunRow | null, DbError>;
@@ -56,6 +89,22 @@ export declare function queryRunsByAnalysis(pool: Querier, analysisId: string, {
     limit?: number;
     offset?: number;
 }): ResultAsync<CortexRunRow[], 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
+ * bounded prompt projection can disclose omitted rows.
+ */
+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
+ * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
+ * contract.
+ */
+export declare function queryRunsForInspection(pool: Querier, analysisId: string, { limit, offset }?: {
+    limit?: number;
+    offset?: number;
+}): ResultAsync<RunPage, DbError>;
 export declare function queryRunsByThread(pool: Querier, analysisId: string, threadId: string, { limit, offset }?: {
     limit?: number;
     offset?: number;

package/dist/state/runs.js

@@ -10,6 +10,14 @@
  * `err(constraint_violation)` via `tryMutation`.
  */
 import { tryMutation, tryQuery } from "../lib/db-result.js";
+export class RunIdentityCollisionError extends Error {
+    runId;
+    constructor(runId) {
+        super(`run id ${runId} already belongs to another analysis`);
+        this.runId = runId;
+        this.name = "RunIdentityCollisionError";
+    }
+}
 /**
  * Raised when `insertRun` collides with the partial-unique index
  * `idx_cortex_runs_active_plan` — i.e., an active run already exists for
@@ -65,6 +73,45 @@ export function insertRun(pool, input) {
         return e;
     });
 }
+/** Reserve a deterministic run id, treating same-analysis PK conflict as redelivery. */
+export function reserveRunById(pool, input) {
+    const now = new Date().toISOString();
+    return tryMutation("runs.reserveRunById", async () => {
+        const result = await pool.query({
+            text: `INSERT INTO cortex_runs
+            (run_id, analysis_id, thread_id, workflow_name,
+             status, started_at, plan_id, mandate_jti, mandate_expires_at)
+            VALUES ($1, $2, $3, $4, 'running', $5, $6, $7, $8)
+            ON CONFLICT (run_id) DO NOTHING
+            RETURNING run_id`,
+            values: [
+                input.runId,
+                input.analysisId,
+                input.threadId ?? null,
+                input.workflowName,
+                now,
+                input.planId ?? null,
+                input.mandateJti ?? null,
+                input.mandateExpiresAt ?? null,
+            ],
+        });
+        return (result.rowCount ?? 0) > 0;
+    }).andThen((inserted) => tryQuery("runs.reserveRunById.reload", async () => {
+        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
+                FROM cortex_runs
+                WHERE run_id = $1`,
+            values: [input.runId],
+        });
+        return result.rows[0] ?? null;
+    }).map((row) => {
+        if (!row || row.analysis_id !== input.analysisId)
+            throw new RunIdentityCollisionError(input.runId);
+        return { row: mapRunRow(row), inserted };
+    }));
+}
 function isPartialUniqueViolation(err) {
     if (err === null || typeof err !== "object")
         return false;
@@ -92,6 +139,38 @@ export function queryActiveRun(pool, analysisId, planId) {
         return row ? mapRunRow(row) : null;
     });
 }
+/**
+ * Every NON-TERMINAL run of an analysis, newest-first and deliberately unbounded.
+ *
+ * The counterpart to {@link queryRunsByAnalysis}, which answers "the newest N runs" — a windowed
+ * question, and the wrong one for a host driving live surfaces. Ordering by `started_at DESC` and
+ * capping means the run most worth watching is the first to fall out: a long analysis still going
+ * while ten short ones start and finish after it leaves the window entirely, so a host reading only
+ * that window loses its progress AND never learns it terminated.
+ *
+ * Unbounded is safe here in a way it is not for the general listing: this result is capped by the
+ * 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.
+ */
+export function queryActiveRunsByAnalysis(pool, analysisId) {
+    return tryQuery("runs.queryActiveRunsByAnalysis", async () => {
+        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')
+            ORDER BY started_at DESC`,
+            values: [analysisId],
+        });
+        return result.rows.map(mapRunRow);
+    });
+}
 export function updateRunStatus(pool, runId, status, error) {
     const now = new Date().toISOString();
     const isTerminal = status === "completed" || status === "partial" || status === "failed" || status === "canceled";
@@ -142,6 +221,77 @@ export function queryRunsByAnalysis(pool, analysisId, { limit = 50, offset = 0 }
         return result.rows.map(mapRunRow);
     });
 }
+/**
+ * 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
+ * bounded prompt projection can disclose omitted rows.
+ */
+export function queryNonTerminalRunsByAnalysis(pool, analysisId, limit = 20) {
+    return tryQuery("runs.queryNonTerminalRunsByAnalysis", async () => {
+        const countResult = await pool.query({
+            text: `SELECT COUNT(*)::int AS total
+            FROM cortex_runs
+            WHERE analysis_id = $1
+              AND status IN ('running','suspended_insufficient_funds')`,
+            values: [analysisId],
+        });
+        const rowsResult = 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
+            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,
+                     run_id DESC
+            LIMIT $2`,
+            values: [analysisId, limit],
+        });
+        return {
+            runs: rowsResult.rows.map(mapRunRow),
+            total: Number(countResult.rows[0]?.total ?? 0),
+        };
+    });
+}
+/**
+ * Read one stable inspection page: running first, then suspended, then
+ * terminal history. This is deliberately separate from
+ * {@link queryRunsByAnalysis}, whose chronological order is an embedder/UI
+ * contract.
+ */
+export function queryRunsForInspection(pool, analysisId, { limit = 50, offset = 0 } = {}) {
+    return tryQuery("runs.queryRunsForInspection", async () => {
+        const countResult = await pool.query({
+            text: "SELECT COUNT(*)::int AS total FROM cortex_runs WHERE analysis_id = $1",
+            values: [analysisId],
+        });
+        const rowsResult = 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
+            FROM cortex_runs
+            WHERE analysis_id = $1
+            ORDER BY CASE status
+                         WHEN 'running' THEN 0
+                         WHEN 'suspended_insufficient_funds' THEN 1
+                         ELSE 2
+                     END,
+                     started_at DESC,
+                     run_id DESC
+            LIMIT $2 OFFSET $3`,
+            values: [analysisId, limit, offset],
+        });
+        return {
+            runs: rowsResult.rows.map(mapRunRow),
+            total: Number(countResult.rows[0]?.total ?? 0),
+        };
+    });
+}
 export function queryRunsByThread(pool, analysisId, threadId, { limit = 50, offset = 0 } = {}) {
     return tryQuery("runs.queryRunsByThread", async () => {
         const result = await pool.query({

package/dist/tasks/data-profile-activity.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The data-profile workflow's activity emissions, as a pure factory over a raw
+ * stream write.
+ *
+ * Extracted from the workflow body for the same reason `createLineageCollector`
+ * and `buildDriftSignature` are: a DBOS workflow body is not reachable from a
+ * unit test — it needs a launched engine, a sandbox, a scripted model, and an
+ * embedder — so the decidable part is lifted out and tested on its own. What is
+ * decidable here is the whole observable contract of this capability: which
+ * phase each moment of a profile reports, and in what words. Those phrases are
+ * what a user reads, so they are the one part of the work that must not be left
+ * to drift.
+ *
+ * What stays in the body is only control flow — where each call sits relative to
+ * the ledger writes. That is not extractable, and the ordering property it
+ * carries (exactly one terminal emission) is guaranteed structurally instead:
+ * there is exactly one `complete` call site and it is the last statement of the
+ * success path, after the terminal ledger write and the authorization revoke, so
+ * anything that throws on the way there reaches the failure path having emitted
+ * no terminal at all.
+ */
+import type { Logger } from "../lib/logger.js";
+/**
+ * Writes one part to the run-event stream. Injected rather than imported so this
+ * module stays free of the durability engine and so a test can record what a
+ * profile would have reported without launching one.
+ */
+export type ActivityWrite = (part: unknown) => Promise<void>;
+/**
+ * The profile's activity channel. One method per moment the body reports, rather
+ * than a generic `emit(phase, text)`: the phrases are normative, and a call site
+ * that passes its own string is a call site that can drift from the spec.
+ *
+ * Every method resolves even when the underlying write fails — see
+ * {@link createProfileActivityEmitter}.
+ *
+ * Five of the contract's phases have no method here, and their absence is a
+ * decision rather than an oversight: `generating-metadata` and
+ * `generating-summary` describe the sandbox-step's post-agent pipeline, which a
+ * profile does not run (its agent delivers everything through `submit_profile`);
+ * `persisting` is defined as step bytes uploading to an artifact store, and a
+ * profile's durable products are the vector index and the ledger row, so it would
+ * describe nothing; `retrying` needs a retry loop, and a profile failure is
+ * terminal with recovery being a fresh attempt; `warning` needs a non-fatal
+ * user-facing warning channel, and the body's two soft conditions (an empty
+ * manifest, a fallback file description) are logged because neither warrants
+ * interrupting the activity line.
+ */
+export interface ProfileActivityEmitter {
+    /** Reported before the sandbox is created — the longest wait in a profile, and the one that precedes the agent entirely. */
+    sandboxInit(): Promise<void>;
+    /** Reported once the sandbox is ready, covering the gap before the agent's first tool call. */
+    agentStarting(): Promise<void>;
+    /** Reported per tool call the profiler agent makes, phrased by the shared translator. */
+    forTool(name: string, input: unknown): Promise<void>;
+    /** Reported for the vector-store pass that indexes per-file descriptions. */
+    indexing(): Promise<void>;
+    /** The success terminal. Emitted only after the terminal ledger write has landed. */
+    complete(): Promise<void>;
+    /** The failure terminal, carrying the same user-safe reason the ledger receives. */
+    failed(reason: string): Promise<void>;
+}
+/** Identity the emitted parts carry — the workflow's synthetic frame, not a real run. */
+export interface ProfileActivityFrame {
+    /**
+     * The constant literal the data-profile workflow uses as its run id. It is the
+     * same string for every analysis, so it identifies nothing; consumers are
+     * required not to key on it (see the data-profile-observation spec). It is
+     * carried because the part contract requires the field and because this is the
+     * frame the workflow already uses for its sandbox identity and scratch path.
+     */
+    readonly runId: string;
+    /** The constant literal step id of the profile's single synthetic step. */
+    readonly stepId: string;
+}
+/**
+ * Build the profile's activity channel over `write`.
+ *
+ * Every emission is awaited by its caller in body order, because `DBOS.writeStream`
+ * allocates a function id and an unawaited write would race the next real operation
+ * for the counter, desynchronising the recorded sequence on replay.
+ *
+ * A failing write is swallowed and logged, never propagated: observation is a
+ * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
+ * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ */
+export declare function createProfileActivityEmitter(write: ActivityWrite, frame: ProfileActivityFrame, logger: Logger): ProfileActivityEmitter;

package/dist/tasks/data-profile-activity.js

@@ -0,0 +1,56 @@
+/**
+ * The data-profile workflow's activity emissions, as a pure factory over a raw
+ * stream write.
+ *
+ * Extracted from the workflow body for the same reason `createLineageCollector`
+ * and `buildDriftSignature` are: a DBOS workflow body is not reachable from a
+ * unit test — it needs a launched engine, a sandbox, a scripted model, and an
+ * embedder — so the decidable part is lifted out and tested on its own. What is
+ * decidable here is the whole observable contract of this capability: which
+ * phase each moment of a profile reports, and in what words. Those phrases are
+ * what a user reads, so they are the one part of the work that must not be left
+ * to drift.
+ *
+ * What stays in the body is only control flow — where each call sits relative to
+ * the ledger writes. That is not extractable, and the ordering property it
+ * carries (exactly one terminal emission) is guaranteed structurally instead:
+ * there is exactly one `complete` call site and it is the last statement of the
+ * success path, after the terminal ledger write and the authorization revoke, so
+ * anything that throws on the way there reaches the failure path having emitted
+ * no terminal at all.
+ */
+import { activityForTool, stepPartId } from "../sandbox/sandbox-step-translate.js";
+/**
+ * Build the profile's activity channel over `write`.
+ *
+ * Every emission is awaited by its caller in body order, because `DBOS.writeStream`
+ * allocates a function id and an unawaited write would race the next real operation
+ * for the counter, desynchronising the recorded sequence on replay.
+ *
+ * A failing write is swallowed and logged, never propagated: observation is a
+ * diagnostic channel, and a dropped frame must not fail a profile that is otherwise
+ * succeeding. This mirrors the sandbox-step producer's stance on the same write.
+ */
+export function createProfileActivityEmitter(write, frame, logger) {
+    // One reconciling id for the profile's single step, so the run-stream fold
+    // collapses every phase transition latest-wins onto one frame rather than
+    // accumulating them. Minted through the shared construction because that
+    // sameness across producers is what makes the fold correct.
+    const id = stepPartId("step-activity", frame.runId, frame.stepId);
+    const emit = async (phase, activity) => {
+        try {
+            await write({ type: "data-step-activity", id, runId: frame.runId, stepId: frame.stepId, phase, activity });
+        }
+        catch (err) {
+            logger.warn("run-event write failed (non-fatal)", { phase, ...logger.errorFields(err) });
+        }
+    };
+    return {
+        sandboxInit: () => emit("sandbox-init", "Starting sandbox"),
+        agentStarting: () => emit("executing", "Running data-profiler"),
+        forTool: (name, input) => emit("executing", activityForTool(name, input)),
+        indexing: () => emit("indexing", "Indexing input descriptions for search"),
+        complete: () => emit("complete", "Profile complete"),
+        failed: (reason) => emit("failed", reason),
+    };
+}