@inflexa-ai/harness 0.12.0 → 0.14.0

package/dist/providers/errors.js

@@ -15,6 +15,7 @@
  * re-authenticating fixes it — which is a different remedy from every other
  * non-retryable 4xx, so it is a different kind.
  */
+import { redactSecrets } from "../input-sanitization.js";
 /**
  * Structural guard for an already-constructed `ProviderError` value. A
  * `ProviderError` is a plain object, not an `Error`, so it cannot be
@@ -71,7 +72,67 @@ export function toProviderError(e, workload) {
             cause: e,
         };
     }
-    return { type: "provider", retryable, message: detail, cause: e };
+    // The `provider` arm composes like its three siblings rather than forwarding
+    // the SDK message verbatim. It has to: when a 4xx body does not parse against
+    // the configured provider's error schema, the AI SDK falls back to
+    // `response.statusText`, so the "detail" is a bare HTTP reason phrase —
+    // `"Bad Request"` — that names neither the call nor the cause, while the
+    // status, the workload, and the body the SDK captured are all still on the
+    // `cause` chain right here.
+    //
+    // Composed strictly AFTER `classifyProviderError` has returned, so message
+    // text can never become a classification input: the harness-providers spec
+    // fixes classification on the HTTP status alone.
+    const status = extractStatus(e);
+    const lead = status === undefined ? `Provider call failed for ${workload}` : `Provider call failed for ${workload} (HTTP ${status})`;
+    // A transport that carries no reason phrase (an HTTP/2 hop yields
+    // `statusText === ""`) leaves `detail` empty; appending it regardless would
+    // trail a bare `": "` on an otherwise complete message.
+    const reason = detail.trim();
+    const diagnosed = reason ? `${lead}: ${reason}` : lead;
+    const body = extractResponseBody(e);
+    return {
+        type: "provider",
+        retryable,
+        // The excerpt trails deliberately — workload and status lead, so a
+        // downstream truncation (`profileFailureReason` cuts the line at 200)
+        // eats the least diagnostic content first.
+        message: body ? `${diagnosed} — response body: ${excerptResponseBody(body)}` : diagnosed,
+        cause: e,
+    };
+}
+/**
+ * Max characters of a captured provider response body carried in a message.
+ *
+ * Derived, not picked: the tightest downstream consumer (`profileFailureReason`,
+ * `tasks/data-profile.ts`) truncates the whole line at 200, and the lead this
+ * excerpt trails — a workload label plus `HTTP <status>` plus a reason phrase —
+ * runs to roughly 80. 120 is therefore the largest round value that cannot evict
+ * that lead.
+ *
+ * Deliberately NOT shared with that consumer's `PROFILE_ERROR_MAX_LEN`: that one
+ * bounds a `varchar` ledger column, this one bounds a message many non-ledger
+ * consumers read, and coupling them would make either one unmovable.
+ */
+const PROVIDER_BODY_EXCERPT_MAX_LEN = 120;
+/**
+ * Single-lined, secret-redacted, length-capped rendering of a captured response body. Bounding happens
+ * here rather than at a consumer because most `ProviderError` consumers truncate nothing at all, and the
+ * one that does would let an unbounded body crowd out the workload and status ahead of it.
+ *
+ * The body is an UNTRUSTED upstream/proxy payload, and this excerpt lands verbatim in the ledger's
+ * `data_profile_error` (surfaced to the UI) and the logs, whereas the composed lead does not — so
+ * secrets are redacted here and nowhere else on the message. Redaction runs on the FULL body before
+ * truncation: a token straddling the cut would otherwise be sliced into an unmatchable fragment that
+ * leaks. `redactSecrets` matches only prefixed formats (API keys, JWTs, bearer tokens, connection
+ * strings) and is safe on biological data, so a legitimate error body passes through intact.
+ */
+function excerptResponseBody(body) {
+    const singleLine = redactSecrets(body).replace(/\s+/g, " ").trim();
+    // Slice by CODE POINT, not UTF-16 unit: a raw byte body can carry astral characters, and a plain
+    // `.slice` could bisect a surrogate pair into a lone half that renders as U+FFFD.
+    const chars = [...singleLine];
+    return chars.length > PROVIDER_BODY_EXCERPT_MAX_LEN ? chars.slice(0, PROVIDER_BODY_EXCERPT_MAX_LEN - 1).join("") + "…" : singleLine;
 }
 /** Max links walked on the `cause` chain looking for a structured status. */
 const MAX_CAUSE_HOPS = 5;
@@ -88,8 +149,13 @@ const CONNECTION_ERROR_CODES = new Set([
     "UND_ERR_SOCKET",
 ]);
 const CONNECTION_ERROR_PATTERN = /fetch failed|socket hang up|network error|connection (?:refused|reset|error|closed)|econnrefused|enotfound|etimedout|terminated/i;
-/** Walk the `cause` chain for the first numeric HTTP status. */
-function extractStatus(err) {
+/**
+ * Walk the `cause` chain for the first numeric HTTP status. The single status
+ * walker: `classifyProviderError` keys on what this returns, so a caller asking
+ * "did the provider layer have a status to classify on?" must ask it here rather
+ * than re-implement the traversal.
+ */
+export function extractStatus(err) {
     let cursor = err;
     for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
         const e = cursor;
@@ -101,6 +167,25 @@ function extractStatus(err) {
     }
     return undefined;
 }
+/**
+ * Walk the `cause` chain for the first captured provider response body.
+ *
+ * This is what recovers a proxy-minted or otherwise non-conforming error body:
+ * the AI SDK keeps the raw bytes on `APICallError.responseBody` even when its
+ * own parse against the provider's error schema fails and its `message` degrades
+ * to the HTTP reason phrase. A blank body is treated as absent — an empty
+ * `— response body:` segment says less than no segment at all.
+ */
+function extractResponseBody(err) {
+    let cursor = err;
+    for (let i = 0; i < MAX_CAUSE_HOPS && cursor; i++) {
+        const e = cursor;
+        if (typeof e.responseBody === "string" && e.responseBody.trim() !== "")
+            return e.responseBody;
+        cursor = e.cause;
+    }
+    return undefined;
+}
 /** Does any link of the `cause` chain look like a transport-level failure? */
 function looksLikeConnectionError(err) {
     let cursor = err;

package/dist/runtime/assemble.d.ts

@@ -21,11 +21,10 @@ import { type ExecuteAnalysisDeps, type ExecuteAnalysisInput, type ExecuteAnalys
 import { type SandboxStepDeps, type SandboxStepInput, type SandboxStepResult } from "../workflows/sandbox-step.js";
 import { type ExecuteTargetAssessmentDeps, type ExecuteTargetAssessmentInput, type ExecuteTargetAssessmentResult } from "../workflows/execute-target-assessment.js";
 import { type DataProfileDeps, type DataProfileWorkflowInput } from "../tasks/data-profile.js";
-import { type EphemeralDeps, type EphemeralResult, type EphemeralWorkflowInput } from "../execution/ephemeral-runner.js";
 /** Registered child sandbox-step callable the parent's child dispatch closes over. */
 export type SandboxStepCallable = (input: SandboxStepInput) => Promise<SandboxStepResult>;
 /**
- * Deps bundles for the five durable workflows. `executeAnalysis` is a builder
+ * Deps bundles for the durable workflows. `executeAnalysis` is a builder
  * because its `sandboxStepCallable` is the registered sandbox-step callable,
  * which does not exist until registration runs inside `assembleCoreRuntime`.
  */
@@ -34,7 +33,6 @@ export interface CoreWorkflowDeps {
     readonly buildExecuteAnalysis: (sandboxStep: SandboxStepCallable) => ExecuteAnalysisDeps;
     readonly executeTargetAssessment: ExecuteTargetAssessmentDeps;
     readonly dataProfile: DataProfileDeps;
-    readonly ephemeral: Omit<EphemeralDeps, "resourcePolicy">;
 }
 /** The registered, callable workflow handles. */
 export interface RegisteredWorkflows {
@@ -42,22 +40,19 @@ export interface RegisteredWorkflows {
     readonly sandboxStep: SandboxStepCallable;
     readonly executeTargetAssessment: (input: ExecuteTargetAssessmentInput) => Promise<ExecuteTargetAssessmentResult>;
     readonly dataProfile: (input: DataProfileWorkflowInput) => Promise<void>;
-    readonly ephemeral: (input: EphemeralWorkflowInput) => Promise<EphemeralResult>;
 }
 /**
- * Conversation-agent deps minus the two workflow callables and the resource
+ * Conversation-agent deps minus the workflow callable and the resource
  * policy — `assembleCoreRuntime` supplies those itself so a caller cannot wire
  * a stale callable or a policy that diverges from the one the workflows see.
  */
-export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "ephemeralWorkflow" | "resourcePolicy">;
+export type ConversationAssemblyDeps = Omit<ConversationAgentDeps, "executeAnalysisWorkflow" | "resourcePolicy">;
 export interface CoreRuntimeDeps {
     readonly conversation: ConversationAssemblyDeps;
     readonly workflows: CoreWorkflowDeps;
     /**
-     * Host resource policy — per-step ceilings, machine budget, ephemeral
-     * sizing. One supply point: assembly distributes it to the planner tools,
-     * `execute_plan` (budget snapshot into workflow input), and the ephemeral
-     * runner. Absent, every consumer keeps its legacy behavior.
+     * Host resource policy — per-step ceilings and machine budget. One supply
+     * point for planner/routing guidance and workflow-input budget snapshots.
      */
     readonly resourcePolicy?: ResourcePolicy;
 }

package/dist/runtime/assemble.js

@@ -19,18 +19,15 @@ import { registerExecuteAnalysis } from "../workflows/execute-analysis.js";
 import { registerSandboxStep } from "../workflows/sandbox-step.js";
 import { registerExecuteTargetAssessment, } from "../workflows/execute-target-assessment.js";
 import { registerDataProfileWorkflow } from "../tasks/data-profile.js";
-import { registerEphemeralWorkflow } from "../execution/ephemeral-runner.js";
 export function assembleCoreRuntime(deps) {
     const { conversation, workflows: wf, resourcePolicy } = deps;
     const sandboxStep = registerSandboxStep(wf.sandboxStep);
     const executeAnalysis = registerExecuteAnalysis(wf.buildExecuteAnalysis(sandboxStep));
     const executeTargetAssessment = registerExecuteTargetAssessment(wf.executeTargetAssessment);
     const dataProfile = registerDataProfileWorkflow(wf.dataProfile);
-    const ephemeral = registerEphemeralWorkflow({ ...wf.ephemeral, resourcePolicy });
     const conversationAgent = createConversationAgent({
         ...conversation,
         executeAnalysisWorkflow: executeAnalysis,
-        ephemeralWorkflow: ephemeral,
         resourcePolicy,
     });
     return {
@@ -40,7 +37,6 @@ export function assembleCoreRuntime(deps) {
             sandboxStep,
             executeTargetAssessment,
             dataProfile,
-            ephemeral,
         },
     };
 }

package/dist/runtime/boot.d.ts

@@ -22,7 +22,7 @@
  *      builds the conversation agent (register-before-launch invariant).
  *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
- *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
  *
@@ -49,7 +49,7 @@ export interface BootHarnessDeps {
     readonly logger: Logger;
     /**
      * Host-specific work that must run AFTER workflow registration and BEFORE
-     * DBOS launch (scheduled sweeps, ephemeral reap, agent-switch install). The
+     * DBOS launch (scheduled sweeps, legacy-row reap, agent-switch install). The
      * booted runtime is not returned until after launch, so this hook captures
      * whatever it needs from the embedder's own composition root.
      */

package/dist/runtime/boot.js

@@ -22,7 +22,7 @@
  *      builds the conversation agent (register-before-launch invariant).
  *   6. `beforeLaunch()` — embedder hook for host-specific pre-launch work that
  *      must attach before DBOS launch re-emits events (scheduled sweeps, an
- *      ephemeral-workflow reap, an agent-switch install). Runs after registration
+ *      legacy-workflow reap, an agent-switch install). Runs after registration
  *      so it may close over the registered callables.
  *   7. `launchDbos(...)` — the last registration-dependent step.
  *

package/dist/runtime/dbos.d.ts

@@ -67,11 +67,10 @@ export declare function shutdownDbos({ logger: injected }: {
     logger: Logger;
 }): Promise<void>;
 /**
- * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
- * called BEFORE `launchDbos`, whose recovery would otherwise re-dispatch them.
- *
- * Ephemeral runs are turn-scoped: a run whose pod died mid-flight has no live
- * awaiter and must never re-execute. DBOS has no "zero recovery" knob, and
+ * Cancel any legacy `ephemeral:`-prefixed PENDING workflow this executor owns
+ * before `launchDbos`, whose recovery would otherwise re-dispatch rows created
+ * by older releases. No current workflow creates this prefix. DBOS has no
+ * "zero recovery" knob, and
  * `launch()` starts recovery itself, so there is no post-launch window to
  * cancel from — the only race-free point is a direct system-DB UPDATE before
  * launch. A CANCELLED row is excluded from the recovery query (which selects

package/dist/runtime/dbos.js

@@ -109,11 +109,10 @@ export async function shutdownDbos({ logger: injected }) {
     }
 }
 /**
- * Cancel any `ephemeral:`-prefixed PENDING workflow this executor owns —
- * called BEFORE `launchDbos`, whose recovery would otherwise re-dispatch them.
- *
- * Ephemeral runs are turn-scoped: a run whose pod died mid-flight has no live
- * awaiter and must never re-execute. DBOS has no "zero recovery" knob, and
+ * Cancel any legacy `ephemeral:`-prefixed PENDING workflow this executor owns
+ * before `launchDbos`, whose recovery would otherwise re-dispatch rows created
+ * by older releases. No current workflow creates this prefix. DBOS has no
+ * "zero recovery" knob, and
  * `launch()` starts recovery itself, so there is no post-launch window to
  * cancel from — the only race-free point is a direct system-DB UPDATE before
  * launch. A CANCELLED row is excluded from the recovery query (which selects
@@ -134,7 +133,7 @@ export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, ex
             values: [Date.now(), executorID],
         });
         if (rowCount && rowCount > 0) {
-            logger.info("swept orphaned ephemeral workflows", { executorID, swept: rowCount });
+            logger.info("swept legacy ephemeral workflow rows", { executorID, swept: rowCount });
         }
     }
     catch (err) {
@@ -142,7 +141,7 @@ export async function sweepEphemeralWorkflows({ pool, logger: injectedLogger, ex
         if (err && typeof err === "object" && "code" in err && err.code === "42P01") {
             return;
         }
-        logger.error("ephemeral sweep failed", { executorID, ...logger.errorFields(err) });
+        logger.error("legacy ephemeral-row sweep failed", { executorID, ...logger.errorFields(err) });
     }
 }
 /** Snapshot of DBOS lifecycle state — read by the readiness probe. */

package/dist/runtime/pools.d.ts

@@ -1,5 +1,6 @@
 /**
- * Per-pod Postgres pool sizing — the single source of truth.
+ * Per-pod Postgres pool sizing and acquisition bounds — the single source of
+ * truth.
  *
  * Cortex runs two pools per pod against the same cluster (see the postgres-storage-backend spec): the
  * application pool (`lib/storage.ts::createPool()`) and the DBOS system-DB
@@ -21,5 +22,18 @@ export declare const DEFAULT_APP_POOL_SIZE = 12;
  * overlap during DBOS recovery, replication / monitoring users.
  */
 export declare const SAFETY_MARGIN = 5;
+/**
+ * How long a caller may wait for a connection from the app pool before the
+ * acquisition fails.
+ *
+ * The driver waits forever by default, which leaves a caller on a saturated
+ * pool with no failure mode at all — only an indefinite hang, indistinguishable
+ * from work still in progress and therefore able to stall the caller's own
+ * in-flight guard permanently. A bound turns that silent stall into a surfaced
+ * error the caller can degrade on. 30s is long enough that a healthy pool under
+ * burst never trips it, and short enough that a wedged caller surfaces well
+ * inside a human's patience.
+ */
+export declare const APP_POOL_ACQUIRE_TIMEOUT_MS = 30000;
 /** Resolve the app pool size from the optional `DB_POOL_MAX` override. */
 export declare function resolveAppPoolSize(dbPoolMax: string | undefined): number;

package/dist/runtime/pools.js

@@ -1,5 +1,6 @@
 /**
- * Per-pod Postgres pool sizing — the single source of truth.
+ * Per-pod Postgres pool sizing and acquisition bounds — the single source of
+ * truth.
  *
  * Cortex runs two pools per pod against the same cluster (see the postgres-storage-backend spec): the
  * application pool (`lib/storage.ts::createPool()`) and the DBOS system-DB
@@ -21,6 +22,19 @@ export const DEFAULT_APP_POOL_SIZE = 12;
  * overlap during DBOS recovery, replication / monitoring users.
  */
 export const SAFETY_MARGIN = 5;
+/**
+ * How long a caller may wait for a connection from the app pool before the
+ * acquisition fails.
+ *
+ * The driver waits forever by default, which leaves a caller on a saturated
+ * pool with no failure mode at all — only an indefinite hang, indistinguishable
+ * from work still in progress and therefore able to stall the caller's own
+ * in-flight guard permanently. A bound turns that silent stall into a surfaced
+ * error the caller can degrade on. 30s is long enough that a healthy pool under
+ * burst never trips it, and short enough that a wedged caller surfaces well
+ * inside a human's patience.
+ */
+export const APP_POOL_ACQUIRE_TIMEOUT_MS = 30_000;
 /** Resolve the app pool size from the optional `DB_POOL_MAX` override. */
 export function resolveAppPoolSize(dbPoolMax) {
     if (dbPoolMax === undefined || dbPoolMax === "")

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

@@ -24,7 +24,7 @@ export interface MountPlanCoords {
     /**
      * Enforced read-only: emit no read-write step mount. The container sees only
      * the read-only analysis tree (plus container-local `/tmp`). Used by the
-     * ephemeral executor, whose prompt promises it physically cannot write files.
+     * a generic read-only agent that must not mutate analysis files.
      */
     readOnly?: boolean;
 }

package/dist/sandbox/sandbox-error.d.ts

@@ -32,7 +32,7 @@
  * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
- * non-workflow consumers (`reaper`, `watchdog`, `ephemeral-runner`,
+ * non-workflow consumers (`reaper`, `watchdog`,
  * `data-profile`, `run-exec`) already handle a thrown failure. They are
  * untouched by this wave.
  */

package/dist/sandbox/sandbox-error.js

@@ -32,7 +32,7 @@
  * step and throws directly, so the seam forwards its `Promise<void>` as-is.)
  * Workflow consumers (`sandbox-step.ts`) already wrap each seam call in
  * `DBOS.runStep`, so the re-thrown error records the step as failed;
- * non-workflow consumers (`reaper`, `watchdog`, `ephemeral-runner`,
+ * non-workflow consumers (`reaper`, `watchdog`,
  * `data-profile`, `run-exec`) already handle a thrown failure. They are
  * untouched by this wave.
  */

package/dist/sandbox/sandbox-step-translate.d.ts

@@ -1,10 +1,23 @@
 /**
  * Pure translation between the agent-loop / sandbox event stream and the
  * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
- * label mapping, the file-tree delta extraction/fold, and the chat-data-part
- * narrowing the `sandbox-step` workflow body composes into its emitters.
+ * reconciliation-id construction, the label mapping, the file-tree delta
+ * extraction/fold, and the chat-data-part narrowing a workflow body composes
+ * into its emitters.
  */
 import type { ChatDataPart, EmitFn } from "../loop/types.js";
+/**
+ * Stable reconciliation id for a step's reconciling parts
+ * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
+ * so the run-stream fold collapses every phase transition latest-wins onto
+ * a single frame. The client keys these by `stepId`, but the server fold
+ * keys by part `id`, so the id MUST be unique per step within the run.
+ *
+ * Every producer of these parts mints its ids here: the id is a
+ * reconciliation contract, and the fold collapses correctly only while all
+ * producers construct it identically.
+ */
+export declare function stepPartId(kind: string, runId: string, stepId: string): string;
 export declare function activityForTool(name: string, input?: unknown): string;
 /** On-change working-tree delta the sandbox executor posts per exec (paths
  *  only; the executor skips directories). */

package/dist/sandbox/sandbox-step-translate.js

@@ -1,9 +1,24 @@
 /**
  * Pure translation between the agent-loop / sandbox event stream and the
  * typed per-step parts the frontend renders. No DBOS, no per-run state — just the
- * label mapping, the file-tree delta extraction/fold, and the chat-data-part
- * narrowing the `sandbox-step` workflow body composes into its emitters.
+ * reconciliation-id construction, the label mapping, the file-tree delta
+ * extraction/fold, and the chat-data-part narrowing a workflow body composes
+ * into its emitters.
  */
+/**
+ * Stable reconciliation id for a step's reconciling parts
+ * (`data-step-activity`, `data-step-file-tree`). One id per (runId, stepId)
+ * so the run-stream fold collapses every phase transition latest-wins onto
+ * a single frame. The client keys these by `stepId`, but the server fold
+ * keys by part `id`, so the id MUST be unique per step within the run.
+ *
+ * Every producer of these parts mints its ids here: the id is a
+ * reconciliation contract, and the fold collapses correctly only while all
+ * producers construct it identically.
+ */
+export function stepPartId(kind, runId, stepId) {
+    return `${kind}-${runId}-${stepId}`;
+}
 /** Friendly live-activity label per sandbox tool id. Falls back to the raw
  *  tool name so a newly added tool still reads sensibly. */
 const TOOL_ACTIVITY = {

package/dist/sandbox/types.d.ts

@@ -241,7 +241,7 @@ export interface CreateSandboxMeta {
      *  a sandbox with none. */
     resources: ResourceSpec;
     /** Enforced read-only: provision with no read-write step mount, only the
-     *  read-only analysis tree. Used by the ephemeral executor. */
+     *  read-only analysis tree for generic read-only agents. */
     readOnly?: boolean;
 }
 /**

package/dist/schemas/validate-plan.d.ts

@@ -22,7 +22,7 @@ export interface ValidatePlanOptions {
      * Host per-step resource ceilings. When present, a step whose declared
      * `resources` exceed them is an error — the planner gets actionable
      * feedback at plan time instead of a silent clamp at sandbox creation.
-     * The plan-generation path passes this; `execute_plan` deliberately does
+     * The plan-generation path passes this; `execute_analysis` plan mode deliberately does
      * not, so stored plans that predate the policy keep running (the
      * sandbox-creation clamp remains their backstop).
      */

package/dist/schemas/workflow-state.d.ts

@@ -7,8 +7,8 @@
 import { z } from "zod";
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
- * this into the planner's output contract and emits it as the `validate_plan` /
- * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * this into the planner's output contract and emits it as the `submit_plan`
+ * arg schema — so each field's meaning belongs in `.describe()`,
  * not in a comment the model never sees.
  */
 export declare const AnalysisStepSchema: z.ZodObject<{

package/dist/schemas/workflow-state.js

@@ -8,8 +8,8 @@ import { z } from "zod";
 // ── Plan structures ─────────────────────────────────────────────────
 /**
  * A step of an analysis plan. `PlanStepSchema` (schemas/plan-schemas.ts) narrows
- * this into the planner's output contract and emits it as the `validate_plan` /
- * `submit_plan` arg schema — so each field's meaning belongs in `.describe()`,
+ * this into the planner's output contract and emits it as the `submit_plan`
+ * arg schema — so each field's meaning belongs in `.describe()`,
  * not in a comment the model never sees.
  */
 export const AnalysisStepSchema = z.object({

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

@@ -101,6 +101,13 @@ export interface DataProfileStatus {
     startedAt: string | null;
     completedAt: string | null;
     result: DataProfileResult | null;
+    /**
+     * The DBOS workflow id of the profile attempt that owns this row — the durable
+     * event stream a consumer subscribes to for this profile's activity. `null` means
+     * this profile's stream is not addressable (see
+     * {@link recordDataProfileWorkflowId}).
+     */
+    workflowId: string | null;
     seedInputFileIds: string[] | null;
 }
 /**
@@ -117,14 +124,59 @@ export interface DataProfileStatus {
  * unseeded — neither is an error, both stay in the ok channel.
  */
 export declare function tryStartDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
-/** 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 declare function tryRetryDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
 /**
  * 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 declare function tryRerunDataProfile(pool: Querier, analysisId: string): ResultAsync<boolean, DbError>;
+/**
+ * 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 declare function recordDataProfileWorkflowId(pool: Querier, analysisId: string, workflowId: string): ResultAsync<boolean, DbError>;
 /**
  * Stamp a claimed-`running` row `completed` and record its result — a terminal
  * write CAS'd on `data_profile_status = 'running'`.