wip v28

Author: geraldarthurdavis

BITCODE_SPEC_V28.md

@@ -470,6 +470,11 @@ Read/Fit result review remains fail-closed:
 - artifact telemetry must subscribe to stream events even when database
   streaming is disabled; database persistence is an additional acceptance gate,
   not the only way to inspect a live failed run.
+- the deployed Terminal harness stream must expose sandbox id, run id, and
+  incremental telemetry artifact lines while the detached sandbox command is
+  still running. Browser-only Network inspection is not sufficient; the
+  operator-visible stream must show phase, agent, generation/tool, parsed
+  output, and failsafe context as first-class Read/Fit run evidence.
 - the harness must enforce an internal runtime budget before the caller's host
   timeout, producing a `blocked_readiness` artifact rather than allowing the
   host to terminate without evidence.

BITCODE_V28_QA.md

@@ -926,6 +926,10 @@ First-run execution boundary:
   and the last visible stream event summaries. A failing command with no
   prompt/context, raw output, parsed/cast output, or phase/agent correlation is
   not enough visibility for live staging-testnet debugging.
+- The Terminal live-run panel must show the active Read id, Deposit id,
+  source commit, sandbox id when available, pipeline run id when available, and
+  incremental `telemetry.jsonl` line summaries while the sandbox command is
+  still running. A state visible only in browser Network logs fails V28 QA.
 - Depository vector recall uses `text-embedding-3-small` by default with
   `encoding_format='float'`, `dimensions=1536`, Supabase
   `deliverable_vectors.embedding vector(1536)`, `ivfflat`,
@@ -1233,11 +1237,14 @@ After either harness run:
    messages when available, raw response content, parsed/cast output when the
    generation was parsed, provider/model identity, usage tokens when supplied,
    and phase/agent/step/failsafe/generation correlation.
-4. Run saved query
+4. Inspect the Terminal live-run panel for the same run id and sandbox id. The
+   panel must include host lifecycle events and incremental telemetry artifact
+   event summaries, not only the final harness completion payload.
+5. Run saved query
    `supabase/queries/v28_qa_terminal_07_pipeline_harness_after_fit.sql`.
-5. Rerun `v28_qa_terminal_06_read_fit_quality_after_read` and
+6. Rerun `v28_qa_terminal_06_read_fit_quality_after_read` and
    `v28_qa_terminal_03_btd_ledger_after_terminal`.
-6. Capture Vercel Sandbox dashboard/log evidence for the same timestamps.
+7. Capture Vercel Sandbox dashboard/log evidence for the same timestamps.
 
 Pass criteria:
 

packages/pipeline-hosts/README.md

@@ -58,10 +58,18 @@ agent, generation, or tool last produced input/output evidence.
 The runner subscribes to stream events for artifact telemetry even when database
 streaming is disabled; database streaming adds persistence, not basic event
 visibility.
+While the pipeline command runs detached, the host polls `telemetry.jsonl` and
+emits each new line as a `telemetry-artifact-event` so Terminal can show
+sandbox id, run id, phase, agent, generation/tool, parsed-output, and failsafe
+context before final artifact readback. Browser Network logs are not the
+operator interface for live Read/Fit debugging.
 The live runner also enforces `BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS`
 (default `240000`) inside the sandbox so a heavyweight pipeline run records a
 blocked-readiness artifact before the calling Vercel Function or local harness
 process reaches its own timeout.
+`BITCODE_PIPELINE_HARNESS_CHECKPOINT_INTERVAL_MS` defaults to `2000` so the
+exported telemetry artifact stays close enough to the live runner for SSE
+tailing without writing on every internal event.
 
 For live model execution, the sandbox runner also needs `OPENAI_API_KEY` in the
 trusted command environment. For local Vercel Sandbox creation, either pull

packages/pipeline-hosts/src/__tests__/vercel-sandbox-host.test.ts

@@ -154,10 +154,16 @@ describe('VercelSandboxPipelineHost', () => {
 
   it('polls detached command artifacts instead of relying on the command stream', async () => {
     const fakeSandbox = new DetachedFakeSandbox();
+    const events: PipelineHarnessHostEvent[] = [];
     const factory: SandboxFactory = {
       create: async () => fakeSandbox,
     };
-    const host = new VercelSandboxPipelineHost({ sandboxFactory: factory });
+    const host = new VercelSandboxPipelineHost({
+      sandboxFactory: factory,
+      onEvent: (event) => {
+        events.push(event);
+      },
+    });
     const plan = buildAssetPackSandboxHarness({
       read: {
         id: 'read-1',
@@ -194,6 +200,14 @@ describe('VercelSandboxPipelineHost', () => {
       stdout: 'detached stdout',
       stderr: '',
     });
+    expect(events).toContainEqual(
+      expect.objectContaining({
+        type: 'telemetry-artifact-event',
+        label: 'detached-run',
+        lineNumber: 1,
+        telemetryEvent: { type: 'harness-complete' },
+      }),
+    );
   });
 
   it('passes access-token auth fields to Sandbox.create when OIDC is unavailable', async () => {

packages/pipeline-hosts/src/asset-pack-harness.ts

@@ -210,7 +210,7 @@ function buildCommands(
       stdoutPath: PIPELINE_STDOUT_PATH,
       stderrPath: PIPELINE_STDERR_PATH,
       maxWaitMs,
-      pollIntervalMs: 5000,
+      pollIntervalMs: 2000,
       required: true,
     });
 
@@ -323,6 +323,7 @@ const DEFAULT_USER_ID = '00000000-0000-4000-8000-000000000000';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const startedAt = new Date().toISOString();
 const harnessMaxRuntimeMs = Number(process.env.BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS || 240000);
+const checkpointIntervalMs = Number(process.env.BITCODE_PIPELINE_HARNESS_CHECKPOINT_INTERVAL_MS || 2000);
 let manifest = null;
 let manifestRoot = null;
 let userId = process.env.BITCODE_PIPELINE_USER_ID || DEFAULT_USER_ID;
@@ -584,7 +585,7 @@ async function writeCheckpoint(reason) {
 
 function scheduleCheckpoint(reason) {
   const now = Date.now();
-  if (now - lastCheckpointAt < 15000) return;
+  if (now - lastCheckpointAt < checkpointIntervalMs) return;
   lastCheckpointAt = now;
   checkpointInFlight = checkpointInFlight
     .catch(() => {})

packages/pipeline-hosts/src/types.ts

@@ -268,6 +268,14 @@ export type PipelineHarnessHostEvent =
       startedAt: string;
       completedAt: string;
     }
+  | {
+      type: 'telemetry-artifact-event';
+      timestamp: string;
+      label: string;
+      telemetryPath: string;
+      lineNumber: number;
+      telemetryEvent: unknown;
+    }
   | {
       type: 'artifacts-read';
       timestamp: string;

packages/pipeline-hosts/src/vercel-sandbox-host.ts

@@ -62,7 +62,7 @@ export class VercelSandboxPipelineHost {
       });
 
       for (const command of plan.commands) {
-        const commandResult = await this.runCommand(sandbox, command);
+        const commandResult = await this.runCommand(sandbox, command, plan.artifactPaths.telemetry);
         commands.push(commandResult);
 
         if (command.required !== false && commandResult.exitCode !== 0) {
@@ -107,7 +107,8 @@ export class VercelSandboxPipelineHost {
 
   private async runCommand(
     sandbox: SandboxSession,
-    command: PipelineHarnessCommand
+    command: PipelineHarnessCommand,
+    telemetryPath?: string
   ): Promise<PipelineHarnessCommandResult> {
     await this.emit({
       type: 'command-started',
@@ -132,7 +133,7 @@ export class VercelSandboxPipelineHost {
         detached: command.detached,
       });
       if (command.detached) {
-        const detachedResult = await this.waitForDetachedCommand(sandbox, command);
+        const detachedResult = await this.waitForDetachedCommand(sandbox, command, telemetryPath);
         exitCode = detachedResult.exitCode;
         stdout = detachedResult.stdout;
         stderr = detachedResult.stderr;
@@ -174,11 +175,13 @@ export class VercelSandboxPipelineHost {
 
   private async waitForDetachedCommand(
     sandbox: SandboxSession,
-    command: PipelineHarnessCommand
+    command: PipelineHarnessCommand,
+    telemetryPath?: string
   ): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
     const startedAt = Date.now();
     const maxWaitMs = command.maxWaitMs ?? 45 * 60 * 1000;
     const pollIntervalMs = command.pollIntervalMs ?? 5000;
+    let emittedTelemetryLineCount = 0;
 
     if (!command.exitCodePath) {
       return {
@@ -189,8 +192,20 @@ export class VercelSandboxPipelineHost {
     }
 
     while (Date.now() - startedAt <= maxWaitMs) {
+      emittedTelemetryLineCount = await this.emitNewTelemetryArtifactEvents(
+        sandbox,
+        command,
+        telemetryPath,
+        emittedTelemetryLineCount
+      );
       const exitCodeText = await this.readTextArtifact(sandbox, command.exitCodePath);
       if (exitCodeText !== null) {
+        emittedTelemetryLineCount = await this.emitNewTelemetryArtifactEvents(
+          sandbox,
+          command,
+          telemetryPath,
+          emittedTelemetryLineCount
+        );
         const parsedExitCode = Number.parseInt(exitCodeText.trim(), 10);
         const [stdout, stderr] = await Promise.all([
           command.stdoutPath ? this.readTextArtifact(sandbox, command.stdoutPath) : Promise.resolve(null),
@@ -205,6 +220,12 @@ export class VercelSandboxPipelineHost {
       await sleep(pollIntervalMs);
     }
 
+    emittedTelemetryLineCount = await this.emitNewTelemetryArtifactEvents(
+      sandbox,
+      command,
+      telemetryPath,
+      emittedTelemetryLineCount
+    );
     const [stdout, stderr] = await Promise.all([
       command.stdoutPath ? this.readTextArtifact(sandbox, command.stdoutPath) : Promise.resolve(null),
       command.stderrPath ? this.readTextArtifact(sandbox, command.stderrPath) : Promise.resolve(null),
@@ -219,6 +240,31 @@ export class VercelSandboxPipelineHost {
     };
   }
 
+  private async emitNewTelemetryArtifactEvents(
+    sandbox: SandboxSession,
+    command: PipelineHarnessCommand,
+    telemetryPath: string | undefined,
+    emittedLineCount: number
+  ): Promise<number> {
+    if (!telemetryPath) return emittedLineCount;
+    const telemetry = await this.readTextArtifact(sandbox, telemetryPath);
+    if (!telemetry) return emittedLineCount;
+
+    const lines = telemetry.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    const nextStartIndex = emittedLineCount > lines.length ? 0 : emittedLineCount;
+    for (let index = nextStartIndex; index < lines.length; index += 1) {
+      await this.emit({
+        type: 'telemetry-artifact-event',
+        timestamp: new Date().toISOString(),
+        label: command.label,
+        telemetryPath,
+        lineNumber: index + 1,
+        telemetryEvent: parseTelemetryLine(lines[index]),
+      });
+    }
+    return lines.length;
+  }
+
   private async readJsonArtifact(sandbox: SandboxSession, path: string): Promise<unknown | null> {
     const text = await this.readTextArtifact(sandbox, path);
     if (!text) return null;
@@ -247,6 +293,17 @@ function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
+function parseTelemetryLine(line: string): unknown {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return {
+      parseError: true,
+      raw: line,
+    };
+  }
+}
+
 function withTimeout<T>(
   promise: Promise<T>,
   timeoutMs: number,

supabase/queries/v28_qa_terminal_06_read_fit_quality_after_read.sql

@@ -1,6 +1,6 @@
 -- Saved query name: v28_qa_terminal_06_read_fit_quality_after_read
 -- Purpose: run after accepting a Read and recording Fit posture. It verifies
--- the commercially critical Read/Fit sequence is bound to the latest deposited
+-- the critical Read/Fit sequence is bound to the latest deposited
 -- repository revision and flags mock/frontier leakage or missing proof posture.
 
 CREATE OR REPLACE FUNCTION pg_temp.v28_qa_terminal_read_fit_quality_after_read()
@@ -346,7 +346,7 @@ BEGIN
         'read_fit_quality_gate'::text,
         jsonb_build_array(
           jsonb_build_object(
-            'commercial_expectation', 'A Read against the current deposited Bitcode data-space must return a proof-bearing AssetPack fit, explicit no-worthy-fit evidence, or blocked-readiness until real pipeline execution evidence exists.',
+            'review_expectation', 'A Read against the current deposited Bitcode data-space must return a proof-bearing AssetPack fit, explicit no-worthy-fit evidence, or blocked-readiness until real pipeline execution evidence exists.',
             'required_positive_controls', jsonb_build_array(
               'repository_full_name matches the latest deposited repository',
               'source_branch present',

uapi/app/api/pipeline-harness/asset-pack/route.ts

@@ -212,6 +212,28 @@ function hasModelProviderCredential(provider: string, env: Record<string, string
   }
 }
 
+function summarizeHarnessPreflight(body: AssetPackHarnessRequest): Record<string, unknown> {
+  const supabaseUrl = process.env.SUPABASE_URL || process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const serviceRole =
+    process.env.SUPABASE_SERVICE_ROLE_KEY ||
+    process.env.SUPABASE_SECRET_KEY ||
+    process.env.SUPABASE_ADMIN_KEY;
+  const budgetMs = Number(process.env.BITCODE_PIPELINE_HARNESS_MAX_RUNTIME_MS || 240000);
+  return {
+    repositoryFullName: body.repositoryFullName || null,
+    sourceBranch: body.sourceBranch || null,
+    sourceCommit: body.sourceCommit || null,
+    readId: body.readId || null,
+    depositId: body.depositId || null,
+    realInferenceEnabled: isEnabled(process.env.BITCODE_ASSET_PACK_REAL_INFERENCE),
+    openaiCredentialProvided: isUsableSecretValue(process.env.OPENAI_API_KEY),
+    supabaseUrlProvided: isUsableSupabaseUrl(supabaseUrl),
+    supabaseServiceRoleProvided: isUsableSecretValue(serviceRole),
+    runtimeBudgetMs: Number.isFinite(budgetMs) ? budgetMs : null,
+    deployedRuntime: isDeployedRuntime(),
+  };
+}
+
 function sourceCredentialsFromEnv(): { username?: string; password?: string } {
   const password =
     process.env.BITCODE_SANDBOX_SOURCE_GIT_PASSWORD ||
@@ -494,6 +516,7 @@ export async function POST(request: NextRequest): Promise<Response> {
             readId: body.readId,
             depositId: body.depositId,
           });
+          emitSse(controller, 'harness-preflight', summarizeHarnessPreflight(body));
 
           const plan = buildAssetPackSandboxHarness({
             mode,
@@ -549,6 +572,11 @@ export async function POST(request: NextRequest): Promise<Response> {
         } catch (runError) {
           emitSse(controller, 'harness-failed', {
             error: runError instanceof Error ? runError.message : String(runError),
+            preflight: summarizeHarnessPreflight(body),
+          });
+          console.error('[bitcode-pipeline-harness-route-failed]', {
+            error: runError instanceof Error ? runError.message : String(runError),
+            preflight: summarizeHarnessPreflight(body),
           });
         } finally {
           controller.close();