V48 (impl-only): LLM call-debug ledger and read first-LLM abort

Add monorepo .tmp/llm-call-debug write path and movable hard-stop after
Setup Plan prepare_concise_context reason. Read debug runner uses Haiku.

Author: geraldarthurdavis

containers/images/pipeliner/README.md

@@ -105,6 +105,28 @@ docker buildx build \
 
 ## Local validation (align with Production)
 
+### Deposit acceptance (seller spine)
+
+From monorepo root — Path **A** LocalHost runner, Path **B** Pipeliner Docker:
+
+```bash
+# Real LLM required for measured options:
+export BITCODE_ASSET_PACK_REAL_INFERENCE=1
+# ANTHROPIC_API_KEY / OPENAI_API_KEY / …
+
+pnpm run accept:deposit-synthesis          # Path A (default)
+pnpm run accept:deposit-synthesis:docker   # Path B (needs Docker)
+pnpm run accept:deposit-synthesis:all      # A then B
+```
+
+Acceptance requires `worthy_deposit_candidates` (or recovered options), **full
+absolute measurement catalog** per option, and **inspectable patch/fileChanges**.
+Reports land under `.tmp/accept-deposit-a|b/` and `.tmp/accept-deposit-summary/`.
+
+Fixture: `fixtures/deposit-manifest.template.json`.
+
+### Host smoke (entry only)
+
 ```bash
 # After build:
 docker run --rm \

containers/images/pipeliner/fixtures/deposit-manifest.template.json

@@ -0,0 +1,26 @@
+{
+  "schema": "bitcode.pipeline-host.manifest",
+  "hostMode": "asset_pack_pipeline",
+  "synthesizeMode": "deposit",
+  "sourceRevision": {
+    "repositoryFullName": "sindresorhus/is-plain-obj",
+    "branch": "main",
+    "commit": "REPLACE_WITH_CLONE_SHA"
+  },
+  "read": {
+    "id": "deposit-acceptance-read",
+    "prompt": "Deposit measured AssetPack options (acceptance fixture)."
+  },
+  "deposit": {
+    "id": "deposit-acceptance",
+    "hasWalletOrAttestationProof": true,
+    "hasAssetMeasurementEvidence": false
+  },
+  "depositSteering": {
+    "obfuscations": "Redact secrets, API keys, and private credentials. Prefer public API surface only. Do not include private source bodies in summaries.",
+    "permissibleSources": [],
+    "impermissibleSources": ["**/.env*", "**/secrets/**", "**/node_modules/**", "**/*credential*"],
+    "demandContext": ["library-api", "type-safety", "plain-object-check"]
+  },
+  "requireAcceptedReadNeed": false
+}

package.json

@@ -63,6 +63,10 @@
     "verify:ui": "node scripts/verify-ui-ssot.mjs",
     "generate:proven": "node scripts/generate-bitcode-proven.mjs",
     "promote:canon": "node scripts/promote-bitcode-canon.mjs",
+    "accept:deposit-synthesis": "node scripts/accept-deposit-synthesis.mjs --path=a",
+    "accept:deposit-synthesis:docker": "node scripts/accept-deposit-synthesis.mjs --path=b",
+    "accept:deposit-synthesis:all": "node scripts/accept-deposit-synthesis.mjs --path=a,b",
+    "debug:read:first-llm": "pnpm --filter @bitcode/pipeline-hosts run qa:read:debug-first-llm",
     "check:canonical-inputs": "node scripts/check-bitcode-canonical-inputs.mjs",
     "check:canon-posture-drift": "node scripts/check-bitcode-canon-posture-drift.mjs",
     "check:spec-family": "node scripts/check-bitcode-spec-family.mjs",

packages/agent-generics/src/diagnostics/instrumentation.ts

@@ -3,6 +3,11 @@ import type { Execution } from '@bitcode/execution-generics/Execution';
 import { log, writePromptIO, writeStepTraceJSON, writeRawLLMIO } from '@bitcode/logger';
 import { DIAG_ENABLED, DIAG_TRACES, DIAG_FULL_TRACES, DIAG_FULL_PROMPTS, DIAG_TRACE_MAX, DIAG_WRITE_PROMPT_IO, DIAG_WRITE_STEP_TRACES } from './config';
 import { collectExecutionTrace, summarizeExecutionTrace } from './trace';
+import {
+  writeLlmCallDebug,
+  shouldHardStopAfterLlmCall,
+  getLlmCallDebugRunDir,
+} from './llm-call-debug';
 
 function getCtx(execution: Execution, sequence?: string) {
   const phase = (execution as any).findUp?.('phase', 'current');
@@ -83,6 +88,36 @@ export async function logLLMSubstepStart(
     content: { systemPrompt, userPrompt, combinedPrompt, ...ctx },
   }).catch(() => {});
 
+  // Monorepo .tmp ledger (call-by-call pipeline debug).
+  try {
+    const f = writeLlmCallDebug({
+      kind: 'request',
+      sequence,
+      phase: ctx.phase != null ? String(ctx.phase) : undefined,
+      agentName: ctx.agentName != null ? String(ctx.agentName) : undefined,
+      step: ctx.step != null ? String(ctx.step) : undefined,
+      failsafe: ctx.failsafe != null ? String(ctx.failsafe) : undefined,
+      path: Array.isArray(ctx.path) ? ctx.path.map(String) : undefined,
+      correlationId: ctx.correlationId != null ? String(ctx.correlationId) : undefined,
+      provider: (llmConfig as any)?.provider,
+      model: llmConfig?.model,
+      systemPrompt,
+      userPrompt,
+      combinedPrompt,
+    });
+    if (f) {
+      log('[llm-call-debug] request written', 'info', {
+        file: f,
+        dir: getLlmCallDebugRunDir(String(ctx.correlationId || '')),
+        agent: ctx.agentName,
+        step: ctx.step,
+        failsafe: ctx.failsafe,
+        generation: sequence,
+        model: llmConfig?.model,
+      });
+    }
+  } catch { /* never break the pipeline for debug I/O */ }
+
   if (!(DIAG_ENABLED || DIAG_FULL_PROMPTS || DIAG_TRACES)) return;
   log('[llm substep] start', 'debug', {
     ...ctx,
@@ -121,6 +156,34 @@ export async function logLLMSubstepSuccess(
     content: { content: output?.content, usage: output?.usage, metadata: output?.metadata },
   }).catch(() => {});
 
+  try {
+    const f = writeLlmCallDebug({
+      kind: 'response',
+      sequence,
+      phase: ctx.phase != null ? String(ctx.phase) : undefined,
+      agentName: ctx.agentName != null ? String(ctx.agentName) : undefined,
+      step: ctx.step != null ? String(ctx.step) : undefined,
+      failsafe: ctx.failsafe != null ? String(ctx.failsafe) : undefined,
+      path: Array.isArray(ctx.path) ? ctx.path.map(String) : undefined,
+      correlationId: ctx.correlationId != null ? String(ctx.correlationId) : undefined,
+      provider: output?.metadata?.provider,
+      model: output?.metadata?.model,
+      content: output?.content,
+      usage: output?.usage,
+    });
+    if (f) {
+      log('[llm-call-debug] response written', 'info', {
+        file: f,
+        agent: ctx.agentName,
+        step: ctx.step,
+        failsafe: ctx.failsafe,
+        generation: sequence,
+        model: output?.metadata?.model,
+        outputLen: String(output?.content || '').length,
+      });
+    }
+  } catch { /* ignore */ }
+
   if (DIAG_ENABLED || DIAG_FULL_PROMPTS || DIAG_TRACES) {
     log('[llm substep] success', 'debug', {
       ...ctx,
@@ -281,18 +344,37 @@ export function logStepTrace(stepExec: Execution, stepName: string) {
 // Optional debug-stop helpers to keep core code minimal
 export function shouldDebugStopAfterFirstReason(substepExec: Execution, sequence: string): boolean {
   try {
-    if (sequence !== 'reason') return false;
-    const flag = String(process?.env?.BITCODE_DEBUG_STOP_AFTER_FIRST_REASON || '').toLowerCase() === '1';
-    if (!flag) return false;
-    const pathArr = (substepExec as any).getPath?.() || [];
-    const isPlanStep = pathArr.includes('plan');
-    const inPrepareFailsafe = pathArr.some((p: string) => String(p).includes('prepare_concise_context'));
-    const isFirstGen = pathArr.includes('gen-0');
-    const ctx = getCtx(substepExec);
-    const agentFilter = process?.env?.BITCODE_DEBUG_STOP_AGENT_FILTER;
-    const agentMatches = agentFilter ? String(ctx.agentName || '').includes(String(agentFilter)) : true;
-    if (isPlanStep && inPrepareFailsafe && isFirstGen && agentMatches) {
-      log('[llm substep] debug-stop', 'info', { ...ctx, reason: 'BITCODE_DEBUG_STOP_AFTER_FIRST_REASON' });
+    const pathArr: string[] = (substepExec as any).getPath?.() || [];
+    const ctx = getCtx(substepExec, sequence);
+    const decision = shouldHardStopAfterLlmCall({
+      sequence,
+      pathArr,
+      phase: ctx.phase != null ? String(ctx.phase) : undefined,
+      agentName: ctx.agentName != null ? String(ctx.agentName) : undefined,
+      step: ctx.step != null ? String(ctx.step) : undefined,
+      failsafe: ctx.failsafe != null ? String(ctx.failsafe) : undefined,
+    });
+    if (decision.stop) {
+      try {
+        writeLlmCallDebug({
+          kind: 'abort',
+          sequence,
+          phase: ctx.phase != null ? String(ctx.phase) : undefined,
+          agentName: ctx.agentName != null ? String(ctx.agentName) : undefined,
+          step: ctx.step != null ? String(ctx.step) : undefined,
+          failsafe: ctx.failsafe != null ? String(ctx.failsafe) : undefined,
+          path: pathArr.map(String),
+          correlationId: ctx.correlationId != null ? String(ctx.correlationId) : undefined,
+          provider: ctx.provider != null ? String(ctx.provider) : undefined,
+          model: ctx.model != null ? String(ctx.model) : undefined,
+          extra: { reason: decision.reason },
+        });
+      } catch { /* ignore */ }
+      log('[llm substep] debug-stop', 'info', {
+        ...ctx,
+        reason: decision.reason || 'BITCODE_DEBUG_STOP_AFTER_FIRST_REASON',
+        debugDir: getLlmCallDebugRunDir(String(ctx.correlationId || '')),
+      });
       return true;
     }
   } catch {}