@inflexa-ai/harness 0.19.0 → 0.19.2

package/dist/sandbox/k8s-client.js

@@ -32,6 +32,11 @@ const MANAGED_BY_VALUE = "cortex";
 const OWNER_WORKFLOW_LABEL = "cortex/owner-workflow-id";
 const RUN_ID_LABEL = "cortex/run-id";
 const STEP_ID_LABEL = "cortex/step-id";
+// OpenCost sanitizes `/` and `-` to `_`, so these arrive at the metering
+// reconciler as cortex_billing_context / cortex_user_id / cortex_analysis_id.
+const BILLING_CONTEXT_LABEL = "cortex/billing-context";
+const USER_ID_LABEL = "cortex/user-id";
+const ANALYSIS_ID_LABEL = "cortex/analysis-id";
 /**
  * Coerce an arbitrary identifier into a valid K8s label value:
  * ≤63 chars, `[A-Za-z0-9._-]` only, starting and ending alphanumeric.
@@ -214,6 +219,17 @@ function buildJobSpec(meta, config, identity) {
         podSpec.tolerations = config.tolerations;
     if (config.runtimeClassName)
         podSpec.runtimeClassName = config.runtimeClassName;
+    // Pod-template placement is load-bearing: the OpenCost reconciler allocates
+    // by pod labels and filters on a non-empty cortex_billing_context — a
+    // Job-only label is invisible to compute metering.
+    const billingLabels = meta.billing
+        ? {
+            [BILLING_CONTEXT_LABEL]: sanitizeLabelValue(meta.billing.billingContextId),
+            [USER_ID_LABEL]: sanitizeLabelValue(meta.billing.userId),
+            [ANALYSIS_ID_LABEL]: sanitizeLabelValue(meta.analysisId),
+            [RUN_ID_LABEL]: sanitizeLabelValue(meta.runId),
+        }
+        : {};
     return {
         apiVersion: "batch/v1",
         kind: "Job",
@@ -227,6 +243,7 @@ function buildJobSpec(meta, config, identity) {
                 [OWNER_WORKFLOW_LABEL]: sanitizeLabelValue(meta.childWorkflowId),
                 [RUN_ID_LABEL]: sanitizeLabelValue(meta.runId),
                 [STEP_ID_LABEL]: sanitizeLabelValue(meta.stepId),
+                ...billingLabels,
             },
         },
         spec: {
@@ -237,6 +254,7 @@ function buildJobSpec(meta, config, identity) {
                     labels: {
                         role: "sandbox",
                         "cortex/sandbox-id": sandboxId,
+                        ...billingLabels,
                     },
                 },
                 spec: podSpec,

package/dist/sandbox/mount-plan.d.ts

@@ -17,6 +17,13 @@
  * (see {@link buildSessionSubPaths}).
  */
 export declare const STEP_SUBDIRS: readonly ["output", "scripts", "figures", "logs", "notebooks"];
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export declare const LIBS_CONTAINER_PATH = "/mnt/libs";
+export declare const REFS_CONTAINER_PATH = "/mnt/refs";
 export interface MountPlanCoords {
     analysisId: string;
     runId: string;

package/dist/sandbox/mount-plan.js

@@ -18,8 +18,13 @@
  */
 import { assertSafeId } from "../workspace/paths.js";
 export const STEP_SUBDIRS = ["output", "scripts", "figures", "logs", "notebooks"];
-const LIBS_CONTAINER_PATH = "/mnt/libs";
-const REFS_CONTAINER_PATH = "/mnt/refs";
+/**
+ * Container mountpoints of the two read-only stores. Exported because they are
+ * also the discovery tools' default read root: a host whose own process sees a
+ * store the way the sandbox does configures nothing further.
+ */
+export const LIBS_CONTAINER_PATH = "/mnt/libs";
+export const REFS_CONTAINER_PATH = "/mnt/refs";
 /**
  * The step tail beneath an analysis's workspace root, in both container and
  * PVC-relative space. The harness owns this layout (workspace-layout spec).

package/dist/sandbox/types.d.ts

@@ -243,6 +243,12 @@ export interface CreateSandboxMeta {
     /** Enforced read-only: provision with no read-write step mount, only the
      *  read-only analysis tree for generic read-only agents. */
     readOnly?: boolean;
+    /** Billing attribution stamped as pod labels for OpenCost compute metering.
+     *  Absent ⇒ the pod is invisible to the metering reconciler (filter-level). */
+    billing?: {
+        billingContextId: string;
+        userId: string;
+    };
 }
 /**
  * The identity minted for a sandbox machine *before* it is spawned — the

package/dist/state/analyses.d.ts

@@ -1,5 +1,5 @@
 /**
- * `cortex_analysis_state` operations — analysis lifecycle and billing context.
+ * `cortex_analysis_state` operations — analysis lifecycle.
  */
 import type { ResultAsync } from "neverthrow";
 import { type DbError } from "../lib/db-result.js";
@@ -9,20 +9,12 @@ import type { Querier } from "./db.js";
  *
  * The seed endpoint is called repeatedly; this function handles both the
  * initial INSERT and subsequent UPDATEs by writing ALL mutable fields on
- * every call. Re-upserts replace `context` and `billing_context` wholesale.
+ * every call. Re-upserts replace `context` wholesale.
  *
  * User identity is derived from the ambient credential's JWT `sub` claim
  * at request time — not persisted in this table.
- *
- * INTENTIONAL: split-attribution across a single run.
- * If the seed re-upserts mid-workflow (e.g., the billing context's VK rotates),
- * in-flight steps that have already issued LLM calls keep the old attribution
- * on those calls, while subsequent steps in the same run pick up the new
- * identity on their next `billedAgent` resolution. This is by design —
- * usage rows contain full per-call attribution, so spend is
- * always assignable even when it crosses a rotation boundary.
  */
-export declare function upsertAnalysis(pool: Querier, resourceId: string, context: string | null, billingContext: Record<string, string> | null, inputFileIds?: string[]): ResultAsync<void, DbError>;
+export declare function upsertAnalysis(pool: Querier, resourceId: string, context: string | null, inputFileIds?: string[]): ResultAsync<void, DbError>;
 export declare function loadAnalysisStatus(pool: Querier, resourceId: string): ResultAsync<{
     status: string;
     context: string | null;
@@ -41,18 +33,3 @@ export declare function suspendAnalysis(pool: Querier, analysisId: string): Resu
  * Only transitions from `suspended_insufficient_funds` → `active`.
  */
 export declare function resumeAnalysis(pool: Querier, analysisId: string): ResultAsync<void, DbError>;
-/**
- * Resolve the persisted billing context for an analysis.
- *
- * Single DB-read chokepoint used by `requireAnalysisBilling` middleware and
- * by any downstream code that needs to re-read billing identity. The driver
- * read is wrapped as a `DbError`; the missing-row / null-billing /
- * unparseable-JSON cases are control-flow throws (a misconfiguration, not a
- * driver failure) that short-circuit the chain and surface verbatim.
- *
- * User identity (`HEADERS.User`) is derived from the ambient credential's
- * JWT `sub` claim by `credential-middleware`, not from the DB.
- */
-export declare function resolveAnalysisBilling(pool: Querier, analysisId: string): ResultAsync<{
-    billingContext: Record<string, string>;
-}, DbError>;

package/dist/state/analyses.js

@@ -1,5 +1,5 @@
 /**
- * `cortex_analysis_state` operations — analysis lifecycle and billing context.
+ * `cortex_analysis_state` operations — analysis lifecycle.
  */
 import { tryMutation, tryQuery } from "../lib/db-result.js";
 /**
@@ -7,40 +7,24 @@ import { tryMutation, tryQuery } from "../lib/db-result.js";
  *
  * The seed endpoint is called repeatedly; this function handles both the
  * initial INSERT and subsequent UPDATEs by writing ALL mutable fields on
- * every call. Re-upserts replace `context` and `billing_context` wholesale.
+ * every call. Re-upserts replace `context` wholesale.
  *
  * User identity is derived from the ambient credential's JWT `sub` claim
  * at request time — not persisted in this table.
- *
- * INTENTIONAL: split-attribution across a single run.
- * If the seed re-upserts mid-workflow (e.g., the billing context's VK rotates),
- * in-flight steps that have already issued LLM calls keep the old attribution
- * on those calls, while subsequent steps in the same run pick up the new
- * identity on their next `billedAgent` resolution. This is by design —
- * usage rows contain full per-call attribution, so spend is
- * always assignable even when it crosses a rotation boundary.
  */
-export function upsertAnalysis(pool, resourceId, context, billingContext, inputFileIds) {
+export function upsertAnalysis(pool, resourceId, context, inputFileIds) {
     const now = new Date().toISOString();
     return tryMutation("analyses.upsertAnalysis", async () => {
         await pool.query({
             text: `INSERT INTO cortex_analysis_state
-            (analysis_id, status, context, billing_context, data_profile_status,
+            (analysis_id, status, context, data_profile_status,
              seed_input_file_ids, created_at, updated_at)
-            VALUES ($1, 'active', $2, $3::jsonb, 'pending', $4::jsonb, $5, $6)
+            VALUES ($1, 'active', $2, 'pending', $3::jsonb, $4, $5)
             ON CONFLICT (analysis_id) DO UPDATE SET
               context = EXCLUDED.context,
-              billing_context = EXCLUDED.billing_context,
               seed_input_file_ids = COALESCE(EXCLUDED.seed_input_file_ids, cortex_analysis_state.seed_input_file_ids),
               updated_at = EXCLUDED.updated_at`,
-            values: [
-                resourceId,
-                context ?? null,
-                billingContext === null ? null : JSON.stringify(billingContext),
-                inputFileIds ? JSON.stringify(inputFileIds) : null,
-                now,
-                now,
-            ],
+            values: [resourceId, context ?? null, inputFileIds ? JSON.stringify(inputFileIds) : null, now, now],
         });
     });
 }
@@ -88,45 +72,3 @@ export function resumeAnalysis(pool, analysisId) {
         });
     });
 }
-/**
- * Resolve the persisted billing context for an analysis.
- *
- * Single DB-read chokepoint used by `requireAnalysisBilling` middleware and
- * by any downstream code that needs to re-read billing identity. The driver
- * read is wrapped as a `DbError`; the missing-row / null-billing /
- * unparseable-JSON cases are control-flow throws (a misconfiguration, not a
- * driver failure) that short-circuit the chain and surface verbatim.
- *
- * User identity (`HEADERS.User`) is derived from the ambient credential's
- * JWT `sub` claim by `credential-middleware`, not from the DB.
- */
-export function resolveAnalysisBilling(pool, analysisId) {
-    return tryQuery("analyses.resolveAnalysisBilling", () => pool.query({
-        text: "SELECT billing_context FROM cortex_analysis_state WHERE analysis_id = $1",
-        values: [analysisId],
-    })).map((result) => {
-        const row = result.rows[0];
-        if (!row) {
-            throw new Error(`resolveAnalysisBilling: no cortex_analysis_state row for analysisId=${analysisId}`);
-        }
-        const rawBilling = row.billing_context;
-        if (rawBilling === null || rawBilling === undefined) {
-            throw new Error(`resolveAnalysisBilling: billing_context missing for analysisId=${analysisId}`);
-        }
-        // JSONB is parsed by `pg` into native objects. Legacy TEXT rows (if any
-        // slipped through) arrive as strings — parse them.
-        let billingContext;
-        if (typeof rawBilling === "string") {
-            try {
-                billingContext = JSON.parse(rawBilling);
-            }
-            catch (err) {
-                throw new Error(`resolveAnalysisBilling: billing_context is not valid JSON for analysisId=${analysisId}: ${err instanceof Error ? err.message : err}`, { cause: err });
-            }
-        }
-        else {
-            billingContext = rawBilling;
-        }
-        return { billingContext };
-    });
-}

package/dist/state/index.d.ts

@@ -8,10 +8,10 @@
  */
 export { initCortexState } from "./init.js";
 export type { Querier } from "./db.js";
-export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.js";
+export { upsertAnalysis, 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, reserveRunById, RunDedupCollisionError, RunIdentityCollisionError, updateRunStatus, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+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 type { InsertRunInput, RunPage, RunReservation } from "./runs.js";
 export { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";

package/dist/state/index.js

@@ -7,9 +7,9 @@
  * specific entity module (e.g. `./state/runs.js`) when narrow.
  */
 export { initCortexState } from "./init.js";
-export { upsertAnalysis, resolveAnalysisBilling, suspendAnalysis, resumeAnalysis, loadAnalysisStatus } from "./analyses.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, promoteFailedToPartial, setRunMandate, // oss-core-managed-ok: run-mandate ledger (nullable; OSS leaves null)
+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 { insertStepExecution, seedStepExecutions, sweepPendingStepExecutions, updateStepExecution, queryStepsByRun } from "./step-executions.js";
 export { setSandboxRef, setActiveExecId, clearSandboxRef, queryActiveSandboxes, reconcileReapedSandbox } from "./active-sandboxes.js";

package/dist/state/init.js

@@ -12,7 +12,7 @@ import { createNoopLogger } from "../lib/console-logger.js";
 // splitting on ';' (see `DDL.split` below), so a semicolon inside a comment cuts
 // the statement it precedes in half and Postgres rejects the fragment.
 const DDL = `
--- Analysis-level state (status, context, data-profile tracking, billing identity).
+-- Analysis-level state (status, context, data-profile tracking).
 --
 -- User identity is derived from the ambient credential's JWT sub claim
 -- at request time — not persisted in this table.
@@ -20,7 +20,6 @@ CREATE TABLE IF NOT EXISTS cortex_analysis_state (
   analysis_id               TEXT PRIMARY KEY,
   status                    TEXT NOT NULL,
   context                   TEXT,
-  billing_context           JSONB,
   -- Nullable: NULL is the honest "no profile" state, which loadDataProfileStatus
   -- collapses to null so a cleared profile is indistinguishable from one that never
   -- existed. The 'pending' default still applies to a row inserted without a status --
@@ -171,14 +170,22 @@ CREATE INDEX IF NOT EXISTS idx_cortex_report_versions_analysis
 -- never acquires one. The thread id carries no foreign key, the same as the
 -- messages rows, thus a purge of a thread cannot reach this row through a cascade
 -- and purgeThread removes it by name.
+--
+-- The two hash columns are the look-before-record markers. rendered_document_hash
+-- holds the hash of the draft that the last preview rendered. seen_document_hash
+-- holds the hash that the last eyes capture saw, copied from the rendered hash.
+-- Each is nullable, because a fresh session has run no preview and no eyes. The
+-- record refuses unless the seen hash equals the hash of the current draft.
 CREATE TABLE IF NOT EXISTS cortex_report_session_state (
-  thread_id     TEXT PRIMARY KEY,
-  analysis_id   TEXT NOT NULL
-                  REFERENCES cortex_analysis_state(analysis_id)
-                  ON DELETE CASCADE,
-  document      JSONB,
-  snapshot      JSONB,
-  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW()
+  thread_id              TEXT PRIMARY KEY,
+  analysis_id            TEXT NOT NULL
+                           REFERENCES cortex_analysis_state(analysis_id)
+                           ON DELETE CASCADE,
+  document               JSONB,
+  snapshot               JSONB,
+  rendered_document_hash TEXT,
+  seen_document_hash     TEXT,
+  created_at             TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 
 CREATE INDEX IF NOT EXISTS idx_cortex_report_session_state_analysis
@@ -483,6 +490,8 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_analysis_state DROP COLUMN IF EXISTS profile",
                 "ALTER TABLE cortex_analysis_state DROP COLUMN IF EXISTS input_files",
                 "ALTER TABLE cortex_analysis_state DROP COLUMN IF EXISTS user_id",
+                // Billing identity is resolved lazily at charge-open time, never persisted.
+                "ALTER TABLE cortex_analysis_state DROP COLUMN IF EXISTS billing_context",
                 // v2 vestiges on cortex_runs.
                 "ALTER TABLE cortex_runs DROP COLUMN IF EXISTS plan",
                 "ALTER TABLE cortex_runs DROP COLUMN IF EXISTS plan_version",
@@ -515,7 +524,6 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_status TEXT",
                 "ALTER TABLE cortex_runs ADD COLUMN IF NOT EXISTS synthesis_reason TEXT",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS data_profile_result JSONB",
-                "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS billing_context JSONB",
                 // Sandbox reliability telemetry (from sandbox-reliability change on main).
                 "ALTER TABLE cortex_step_executions ADD COLUMN IF NOT EXISTS attempts INTEGER NOT NULL DEFAULT 1",
                 "ALTER TABLE cortex_step_executions ADD COLUMN IF NOT EXISTS last_error_class TEXT",
@@ -552,6 +560,11 @@ export async function initCortexState(pool, injected) {
                 "ALTER TABLE cortex_step_executions ADD COLUMN IF NOT EXISTS child_workflow_id TEXT",
                 "CREATE INDEX IF NOT EXISTS idx_cortex_step_exec_child_workflow " + "ON cortex_step_executions(child_workflow_id)",
                 "ALTER TABLE cortex_analysis_state ADD COLUMN IF NOT EXISTS seed_input_file_ids JSONB",
+                // The look-before-record markers of a report session. Nullable and
+                // unbackfilled: a session with no preview and no eyes carries neither hash,
+                // which is the honest state, thus an existing row reads back as never-seen.
+                "ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS rendered_document_hash TEXT",
+                "ALTER TABLE cortex_report_session_state ADD COLUMN IF NOT EXISTS seen_document_hash TEXT",
                 // Databases created before `data_profile_status` became nullable still
                 // 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.

package/dist/state/report-session-state.d.ts

@@ -42,6 +42,10 @@ export interface ReportSessionState {
     readonly document: DraftDocument | null;
     /** The pinned snapshot, or `null` before the pin writes it. */
     readonly snapshot: ReportSnapshot | null;
+    /** The hash of the draft that the last preview rendered, or `null` before the first preview. */
+    readonly renderedDocumentHash: string | null;
+    /** The hash that the last eyes capture saw, or `null` before the first look. */
+    readonly seenDocumentHash: string | null;
     readonly createdAt: Date;
 }
 /** The snapshot and the anchor of a row to create. */
@@ -69,6 +73,17 @@ export interface PersistDocumentInput {
  * this turn must read the state again. `absent` means no row holds the thread.
  */
 export type PersistOutcome = "persisted" | "conflict" | "absent";
+/**
+ * The outcome of a stamp. `stamped` wrote the hash on the row. `absent` means that no row holds the
+ * thread, thus the stamp wrote nothing. A stamp reads nothing before the write.
+ */
+export type StampOutcome = "stamped" | "absent";
+/**
+ * The outcome of the seen stamp. `stamped` copied a rendered hash onto the seen hash. `no-rendered`
+ * means that the row holds no rendered hash, thus no preview stamped one and the copy found none.
+ * `absent` means that no row holds the thread.
+ */
+export type SeenStampOutcome = "stamped" | "no-rendered" | "absent";
 /**
  * A stored row that a read cannot parse with the current schemas. It names the
  * thread id and the part that failed, and it carries the reduced issues.
@@ -100,6 +115,18 @@ export interface ReportSessionStateStore {
      * concurrent turn landed first, and `absent` means no row holds the thread.
      */
     persistDocument(input: PersistDocumentInput): ResultAsync<PersistOutcome, DbError>;
+    /**
+     * Stamp the rendered-document hash on the row. The preview calls it when the page lands, thus the row
+     * holds the hash of the draft that the page shows. `absent` means that no row holds the thread.
+     */
+    stampRendered(threadId: string, hash: string): ResultAsync<StampOutcome, DbError>;
+    /**
+     * Copy the rendered hash onto the seen hash. The eyes call it after a capture, thus the seen hash holds
+     * the hash of the draft that the picture shows, and never the current one. The operation reports whether
+     * a rendered hash existed to copy. `no-rendered` means that the row holds none, thus no preview stamped
+     * one. `absent` means that no row holds the thread.
+     */
+    stampSeen(threadId: string): ResultAsync<SeenStampOutcome, DbError>;
 }
 export interface ReportSessionStateStoreDeps {
     readonly pool: Pool;

package/dist/state/report-session-state.js

@@ -33,7 +33,7 @@ import { DraftDocumentSchema } from "../report-model/draft.js";
 import { parseSnapshot, reduceIssues } from "./snapshot-parse.js";
 const _assertReadError = true;
 /** The full row projection every read shares. */
-const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, created_at";
+const STATE_COLUMNS = "thread_id, analysis_id, document, snapshot, rendered_document_hash, seen_document_hash, created_at";
 /**
  * The insert. The row carries the snapshot at creation, and the document lands later
  * through `persistDocument`. ON CONFLICT DO NOTHING keeps the first row, thus a
@@ -77,6 +77,8 @@ function rowToState(row) {
         analysisId: row.analysis_id,
         document,
         snapshot,
+        renderedDocumentHash: row.rendered_document_hash,
+        seenDocumentHash: row.seen_document_hash,
         createdAt: row.created_at,
     });
 }
@@ -146,5 +148,30 @@ export function createReportSessionStateStore({ pool }) {
             return row.updated > 0 ? "persisted" : "conflict";
         });
     }
-    return { readState, writeSnapshot, persistDocument };
+    function stampRendered(threadId, hash) {
+        return tryMutation("report-session-state.stampRendered", async () => {
+            const { rowCount } = await pool.query({
+                text: "UPDATE cortex_report_session_state SET rendered_document_hash = $2 WHERE thread_id = $1",
+                values: [threadId, hash],
+            });
+            return (rowCount ?? 0) > 0 ? "stamped" : "absent";
+        });
+    }
+    function stampSeen(threadId) {
+        return tryMutation("report-session-state.stampSeen", async () => {
+            // The seen hash takes the rendered hash of the same row. A copy inside the statement keeps the
+            // two markers on one row, thus the eyes copy the rendered hash and never the current one. The
+            // `RETURNING` clause reads the copied rendered hash back, thus the caller tells a real stamp from
+            // a row that holds no rendered hash to copy.
+            const { rows } = await pool.query({
+                text: "UPDATE cortex_report_session_state SET seen_document_hash = rendered_document_hash WHERE thread_id = $1 RETURNING rendered_document_hash AS copied",
+                values: [threadId],
+            });
+            const row = rows[0];
+            if (row === undefined)
+                return "absent";
+            return row.copied === null ? "no-rendered" : "stamped";
+        });
+    }
+    return { readState, writeSnapshot, persistDocument, stampRendered, stampSeen };
 }

package/dist/state/runs.d.ts

@@ -83,6 +83,16 @@ export declare function queryActiveRun(pool: Querier, analysisId: string, planId
  */
 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>;
+/**
+ * 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.
+ */
+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 }?: {

package/dist/state/runs.js

@@ -183,6 +183,27 @@ export function updateRunStatus(pool, runId, status, error) {
         });
     });
 }
+/**
+ * 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.
+ */
+export function markRunCanceledIfActive(pool, runId, reason) {
+    const now = new Date().toISOString();
+    return tryMutation("runs.markRunCanceledIfActive", async () => {
+        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')`,
+            values: [runId, now, reason],
+        });
+        return (result.rowCount ?? 0) > 0;
+    });
+}
 export function promoteFailedToPartial(pool, runId) {
     return tryMutation("runs.promoteFailedToPartial", async () => {
         const result = await pool.query({

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

@@ -23,6 +23,7 @@ import type { RunAuthorization, RunAuthorizer } from "../execution/run-authorize
 import type { StagedInput } from "../execution/staged-input.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
 import type { Logger } from "../lib/logger.js";
+import type { ResolveBilling } from "../billing/resolver.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { ChatProvider, EmbeddingProvider } from "../providers/types.js";
 import type { SandboxClient } from "../sandbox/client.js";
@@ -56,6 +57,9 @@ export interface DataProfileDeps extends EnvironmentStorePaths {
     readonly skillsDir: string;
     /** LLM usage-accounting seam for the profiler agent loop; omitted falls back to the no-op recorder. */
     readonly usageRecorder?: UsageRecorder;
+    /** Resolves the billing context stamped as the sandbox pod's OpenCost
+     *  labels. Absent in upstream-less (dev/OSS) wiring — pods spawn unlabeled. */
+    readonly resolveBilling?: ResolveBilling;
 }
 /**
  * Workflow input. JSON-serialisable — DBOS persists it as the workflow's

package/dist/tasks/data-profile.js

@@ -42,6 +42,8 @@ import { ensureSearchIndex, searchIndexName } from "../workspace/search-config.j
 import { DATA_PROFILE_RUN_LITERAL } from "../contracts/data-profile.js";
 const DATA_PROFILE_STEP_LITERAL = "profile";
 const DATA_PROFILE_AGENT_ID = "data-profiler";
+/** Resolved-header key carrying the billing-context id (see `ResolveBilling`). */
+const BILLING_CONTEXT_HEADER = "X-Inflexa-Billing-Context";
 /** Sandbox-server exec budget for the profile run. */
 const DEFAULT_DEADLINE_MS = 300_000;
 /** Build the canonical artifact path for a staged input file. */
@@ -226,12 +228,24 @@ export async function runDataProfileBody(input, deps) {
         // from the agent loop would leave the longest wait of all unreported — the same defect the
         // run panel's activity readout was built to remove.
         await activity.sandboxInit();
+        let billingContextId;
+        if (deps.resolveBilling) {
+            try {
+                billingContextId = (await deps.resolveBilling(childSession))[BILLING_CONTEXT_HEADER];
+            }
+            catch (err) {
+                logger.error("[billing] data-profile billing resolution failed", logger.errorFields(err));
+            }
+            if (!billingContextId)
+                logger.error("[billing] sandbox spawned without billing labels");
+        }
         const sandbox = await deps.sandboxClient.createSandbox({
             runId: DATA_PROFILE_RUN_LITERAL,
             stepId: DATA_PROFILE_STEP_LITERAL,
             analysisId,
             childWorkflowId: workflowId,
             resources: estimateDataProfileResources(stagedInputs),
+            billing: billingContextId ? { billingContextId, userId: childSession.identity.user } : undefined,
         }, mintSandboxIdentity(DATA_PROFILE_RUN_LITERAL));
         try {
             // Checkpointed clock, not `Date.now()`: `awaitExec` gates on this absolute

package/dist/tasks/extract-values-script.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The fixed extraction script and its wire protocol.
+ *
+ * The extraction arm runs this one Python script in the sandbox. The script reads one JSON input: a list
+ * of path, format, and hash triples. For each triple the script hashes the file bytes with a streamed
+ * sha256 before any read. If the on-disk hash does not match the pinned hash, the script refuses the file
+ * as a typed error. If the hash matches, the script reads the file from the read-only analysis mount, and
+ * it parses the file by the carried format. A parquet file uses pyarrow. The script emits one JSON map:
+ * each path to its rows, or to a typed error. The script decides nothing else. It applies no filter and no
+ * projection.
+ *
+ * The host decides the format one time, and the request carries it. Thus the script derives no reader from
+ * an extension, and it refuses a request that names no format. The JSON arm obeys the strict host shape, an
+ * array of flat objects, thus a shape that the host refuses is a refusal here too and it never comes back
+ * as a table that pandas inferred.
+ *
+ * The harness holds the script as a string constant, thus the package ships no separate asset file. The
+ * script reaches the container as the argument of `python3 -c`. The input reaches the container as one
+ * environment variable.
+ */
+import { z } from "zod";
+/**
+ * The environment variable that carries the script input. The workflow body sets it to the JSON list of
+ * path, format, and hash triples. The script reads it back one time.
+ */
+export declare const EXTRACTION_INPUT_ENV = "CORTEX_EXTRACTION_REQUESTS";
+/**
+ * One artifact row, as plain cells. A text-backed format holds a numeric column as a string, thus a cell
+ * is a string or a number.
+ */
+declare const ExtractionRowSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+export type ExtractionRow = z.infer<typeof ExtractionRowSchema>;
+/**
+ * The outcome for one path. A clean read gives the rows. A per-file read fault gives a typed error, and
+ * the script still emits the map. The arm keeps the rows and drops the error, thus a failed path reads as
+ * an unread artifact downstream.
+ */
+declare const ExtractOutcomeSchema: z.ZodUnion<readonly [z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>;
+export type ExtractOutcome = z.infer<typeof ExtractOutcomeSchema>;
+/** The script output: each requested path to its outcome. */
+export declare const ExtractValuesResultSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
+    rows: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>, z.ZodObject<{
+    error: z.ZodObject<{
+        type: z.ZodString;
+        message: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>]>>;
+export type ExtractValuesResult = z.infer<typeof ExtractValuesResultSchema>;
+/**
+ * The one extraction script. The workflow body runs it as the argument of `python3 -c`. The script reads
+ * the request list from `CORTEX_EXTRACTION_REQUESTS`, and it emits the value map to stdout.
+ *
+ * The Python comments obey the same Simplified Technical English rule as the harness comments.
+ */
+export declare const EXTRACTION_SCRIPT = "import hashlib\nimport json\nimport math\nimport os\nimport sys\n\nimport pandas as pd\n\n\ndef sha256_of(path):\n    # The host pins the exact bytes with a streamed sha256, in the \"sha256:<hex>\" form. Mirror that form\n    # here, and stream the file in blocks, thus a large file never loads fully into memory.\n    digest = hashlib.sha256()\n    with open(path, \"rb\") as handle:\n        for block in iter(lambda: handle.read(1024 * 1024), b\"\"):\n            digest.update(block)\n    return \"sha256:\" + digest.hexdigest()\n\n\ndef coerce_cell(value):\n    # A null cell becomes None, thus the record drops the key.\n    if value is None:\n        return None\n    # A numpy scalar becomes a plain Python scalar.\n    if hasattr(value, \"item\"):\n        try:\n            value = value.item()\n        except (ValueError, TypeError):\n            return str(value)\n    if isinstance(value, bool):\n        return \"true\" if value else \"false\"\n    if isinstance(value, float):\n        if math.isnan(value) or math.isinf(value):\n            return None\n        return value\n    if isinstance(value, int):\n        return value\n    if isinstance(value, str):\n        return value\n    return str(value)\n\n\ndef read_frame(path, fmt):\n    # pyarrow reads the parquet columnar format.\n    if fmt == \"parquet\":\n        return pd.read_parquet(path, engine=\"pyarrow\")\n    if fmt == \"tsv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, and the\n        # host parser keeps it too. A default read turns each into NaN, and the row builder drops the key.\n        return pd.read_csv(path, sep=\"\\t\", dtype=str, keep_default_na=False)\n    if fmt == \"csv\":\n        # keep_default_na=False keeps a literal cell such as \"NA\" or an empty string as its text, thus a\n        # text cell survives and the row keeps the key.\n        return pd.read_csv(path, dtype=str, keep_default_na=False)\n    # The host decides the format for both arms. A request with no decided format is a protocol fault, thus\n    # the file refuses here and no reader guesses at it.\n    raise ValueError(\"the request names no supported format: \" + str(fmt))\n\n\ndef json_rows(path):\n    # The host reads a JSON table as an array of flat objects, and it refuses any other shape. Obey the\n    # same shape here. An inference pass would turn a shape that the host refuses into a different table.\n    with open(path, \"rb\") as handle:\n        value = json.load(handle)\n    if not isinstance(value, list):\n        raise ValueError(\"the JSON top-level value is not an array\")\n    rows = []\n    for item in value:\n        if not isinstance(item, dict):\n            raise ValueError(\"a JSON array item is not an object\")\n        row = {}\n        for key, cell in item.items():\n            if isinstance(cell, (dict, list)):\n                raise ValueError(\"a JSON cell holds a nested value\")\n            coerced = coerce_cell(cell)\n            if coerced is not None:\n                row[str(key)] = coerced\n        rows.append(row)\n    return rows\n\n\ndef rows_of(frame):\n    # A null cell becomes None before the record build, thus a missing cell drops.\n    clean = frame.astype(object).where(pd.notnull(frame), None)\n    records = clean.to_dict(orient=\"records\")\n    rows = []\n    for record in records:\n        row = {}\n        for key, value in record.items():\n            cell = coerce_cell(value)\n            if cell is not None:\n                row[str(key)] = cell\n        rows.append(row)\n    return rows\n\n\ndef rows_for(path, fmt):\n    # The JSON arm reads the strict host shape itself. Each other format reads through pandas.\n    if fmt == \"json\":\n        return json_rows(path)\n    return rows_of(read_frame(path, fmt))\n\n\ndef main():\n    raw = os.environ.get(\"CORTEX_EXTRACTION_REQUESTS\", \"[]\")\n    requests = json.loads(raw)\n    out = {}\n    for request in requests:\n        path = request[\"path\"]\n        fmt = request.get(\"format\")\n        expected = request[\"hash\"]\n        try:\n            # Hash the file before any read. A file that drifted from the pin never reaches the reader, thus\n            # the extraction never gives back drifted bytes for the gate to match against.\n            actual = sha256_of(path)\n            if actual != expected:\n                out[path] = {\n                    \"error\": {\n                        \"type\": \"hash-mismatch\",\n                        \"message\": f\"the pinned hash {expected} does not match the on-disk hash {actual}\",\n                    }\n                }\n                continue\n            out[path] = {\"rows\": rows_for(path, fmt)}\n        except Exception as exc:\n            # A per-file read fault lands as a typed error, and the map still holds each other path.\n            out[path] = {\"error\": {\"type\": \"read-fault\", \"message\": str(exc)}}\n    json.dump(out, sys.stdout)\n\n\nmain()\n";
+export {};