@springbrand/agent-runtime 0.2.0-alpha.72 → 0.3.0-alpha.1

package/src/{db/steer.repo.ts → submission/steer-repository.ts}

@@ -4,6 +4,7 @@ export interface PendingSteer {
   steerId: string;
   submissionId: string;
   messageId: string;
+  harnessEntryId: string | null;
   canonicalJson: string;
   uiMessageJson: string | null;
   createdAt: number;
@@ -13,6 +14,7 @@ type PendingSteerRow = {
   steer_id: string;
   submission_id: string;
   message_id: string;
+  harness_entry_id: string | null;
   canonical_json: string;
   ui_message_json: string | null;
   created_at: number;
@@ -23,6 +25,7 @@ function mapRow(row: PendingSteerRow): PendingSteer {
     steerId: row.steer_id,
     submissionId: row.submission_id,
     messageId: row.message_id,
+    harnessEntryId: row.harness_entry_id,
     canonicalJson: row.canonical_json,
     uiMessageJson: row.ui_message_json,
     createdAt: row.created_at,
@@ -35,28 +38,29 @@ export class SteerRepository {
   insert(steer: PendingSteer): void {
     this.sql`
       INSERT INTO pi_pending_steers (
-        steer_id, submission_id, message_id, canonical_json,
+        steer_id, submission_id, message_id, harness_entry_id, canonical_json,
         ui_message_json, created_at
       ) VALUES (
         ${steer.steerId}, ${steer.submissionId}, ${steer.messageId},
-        ${steer.canonicalJson}, ${steer.uiMessageJson}, ${steer.createdAt}
+        ${steer.harnessEntryId}, ${steer.canonicalJson},
+        ${steer.uiMessageJson}, ${steer.createdAt}
       )
     `;
   }
 
   listForSubmission(submissionId: string): PendingSteer[] {
     return this.sql<PendingSteerRow>`
-      SELECT steer_id, submission_id, message_id, canonical_json,
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
              ui_message_json, created_at
       FROM pi_pending_steers
       WHERE submission_id = ${submissionId}
-      ORDER BY created_at ASC, rowid ASC
+      ORDER BY rowid ASC
     `.map(mapRow);
   }
 
   findByMessageId(messageId: string): PendingSteer | null {
     const row = this.sql<PendingSteerRow>`
-      SELECT steer_id, submission_id, message_id, canonical_json,
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
              ui_message_json, created_at
       FROM pi_pending_steers
       WHERE message_id = ${messageId}
@@ -64,6 +68,24 @@ export class SteerRepository {
     return row ? mapRow(row) : null;
   }
 
+  findByHarnessEntryId(entryId: string): PendingSteer | null {
+    const row = this.sql<PendingSteerRow>`
+      SELECT steer_id, submission_id, message_id, harness_entry_id, canonical_json,
+             ui_message_json, created_at
+      FROM pi_pending_steers
+      WHERE harness_entry_id = ${entryId}
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  linkHarnessEntry(messageId: string, entryId: string): void {
+    this.sql`
+      UPDATE pi_pending_steers
+      SET harness_entry_id = ${entryId}
+      WHERE message_id = ${messageId}
+    `;
+  }
+
   deleteByMessageId(messageId: string): void {
     this.sql`
       DELETE FROM pi_pending_steers

package/src/telemetry/contract.ts

@@ -88,6 +88,12 @@ export interface TelemetryPayloadByType {
     readonly generationId: string;
     readonly outcome: "completed" | "failed" | "cancelled";
     readonly durationMs?: number;
+    readonly responseHeadersMs?: number;
+    readonly firstRawEventMs?: number;
+    readonly firstMeaningfulEventMs?: number;
+    readonly firstTextEventMs?: number;
+    readonly sourceWaitMs?: number;
+    readonly forwardingOverheadMs?: number;
     readonly inputTokens?: number;
     readonly outputTokens?: number;
     readonly totalTokens?: number;
@@ -288,6 +294,12 @@ function assertPayload(
   }
   for (const field of [
     "durationMs",
+    "responseHeadersMs",
+    "firstRawEventMs",
+    "firstMeaningfulEventMs",
+    "firstTextEventMs",
+    "sourceWaitMs",
+    "forwardingOverheadMs",
     "inputTokens",
     "outputTokens",
     "totalTokens",

package/src/telemetry/coordinator.ts

@@ -4,6 +4,8 @@ import type { TelemetryOutboxWriter } from "./recorder";
 import { TelemetryRecorder } from "./recorder";
 import { RuntimeTelemetry } from "./runtime-telemetry";
 import type { AgentTelemetryBinding } from "./contract";
+import type { PiGenerationLifecycleEvent } from "../models";
+import type { TemporaryAgentLifecycleEvent } from "../tools/temporary-agent/coordinator";
 
 const TELEMETRY_COLD_BUFFER_LIMIT = 1_000;
 
@@ -93,6 +95,69 @@ export class RuntimeTelemetryCoordinator {
     }
   }
 
+  generation(submissionId: string, event: PiGenerationLifecycleEvent): void {
+    if (event.type === "started") {
+      this.capture("generationStarted", {
+        submissionId,
+        generationId: event.generationId,
+        provider: event.provider,
+        model: event.model,
+        input: event.input,
+        occurredAt: event.timestamp,
+      });
+      return;
+    }
+    this.capture("generationFinished", {
+      submissionId,
+      generationId: event.generationId,
+      outcome: event.outcome === "success" ? "completed"
+        : event.outcome === "cancelled" ? "cancelled" : "failed",
+      durationMs: event.durationMs,
+      responseHeadersMs: event.responseHeadersMs,
+      firstRawEventMs: event.firstRawEventMs,
+      firstMeaningfulEventMs: event.firstMeaningfulEventMs,
+      firstTextEventMs: event.firstTextEventMs,
+      sourceWaitMs: event.sourceWaitMs,
+      forwardingOverheadMs: event.forwardingOverheadMs,
+      ...(event.usage ? {
+        inputTokens: event.usage.input,
+        outputTokens: event.usage.output,
+        totalTokens: event.usage.totalTokens,
+        cost: event.usage.cost.total,
+      } : {}),
+      ...(event.errorName ? { error: event.errorName } : {}),
+      ...(event.output ? { output: event.output } : {}),
+      occurredAt: event.timestamp,
+    });
+  }
+
+  temporaryAgent(
+    submissionId: string,
+    toolCallId: string,
+    event: TemporaryAgentLifecycleEvent,
+  ): void {
+    const identity = { submissionId, toolCallId, subagentId: `temporary:${toolCallId}` };
+    if (event.type === "started") {
+      this.capture("subagentStarted", {
+        ...identity,
+        agentType: event.request.subagentName,
+        prompt: { instructions: event.request.instructions, task: event.request.task },
+        occurredAt: event.occurredAt,
+      });
+      return;
+    }
+    this.capture("subagentFinished", {
+      ...identity,
+      outcome: event.outcome,
+      durationMs: event.durationMs,
+      occurredAt: event.occurredAt,
+      ...(event.output === undefined ? {} : { output: event.output }),
+      ...(event.error === undefined ? {} : {
+        error: event.error instanceof Error ? event.error.message : String(event.error),
+      }),
+    });
+  }
+
   recover(ensureReady: () => Promise<void>): void {
     if (!this.options.outbox()?.hasPending()) return;
     this.options.waitUntil(

package/src/telemetry/delivery.ts

@@ -1,9 +1,9 @@
 import type {
   StoredTelemetryOutboxEvent,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   TELEMETRY_OUTBOX_BATCH_SIZE,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   assertUniversalTelemetryEvent,
   type AgentTelemetryPort,

package/src/telemetry/index.ts

@@ -5,3 +5,8 @@ export * from "./ids";
 export * from "./recorder";
 export * from "./runtime-telemetry";
 export * from "./sanitize";
+export * from "./model-usage";
+export * from "./repository";
+export * from "./runtime-event-repository";
+export * from "./subagent-lifecycle";
+export * from "./turn-events";

package/src/{model-usage.ts → telemetry/model-usage.ts}

@@ -1,5 +1,5 @@
 import type { Api, AssistantMessage, Model } from "@earendil-works/pi-ai";
-import type { RuntimeModelUsageEvent } from "./kernel/bindings";
+import type { RuntimeModelUsageEvent } from "../config/ports";
 
 type ModelUsage = Pick<RuntimeModelUsageEvent,
   "api" | "provider" | "model" | "responseModel" | "stopReason" | "usage"

package/src/telemetry/recorder.ts

@@ -1,7 +1,7 @@
 import type {
   NewTelemetryOutboxEvent,
   TelemetryOutboxInsertResult,
-} from "../db/telemetry-outbox.repo";
+} from "./repository";
 import {
   assertUniversalTelemetryEvent,
   type TelemetryPrivacyMode,

package/src/telemetry/runtime-telemetry.ts

@@ -188,6 +188,12 @@ export class RuntimeTelemetry {
     generationId: string;
     outcome: "completed" | "failed" | "cancelled";
     durationMs?: number;
+    responseHeadersMs?: number;
+    firstRawEventMs?: number;
+    firstMeaningfulEventMs?: number;
+    firstTextEventMs?: number;
+    sourceWaitMs?: number;
+    forwardingOverheadMs?: number;
     inputTokens?: number;
     outputTokens?: number;
     totalTokens?: number;
@@ -204,6 +210,12 @@ export class RuntimeTelemetry {
       generationId: input.generationId,
       outcome: input.outcome,
       ...(input.durationMs === undefined ? {} : { durationMs: input.durationMs }),
+      responseHeadersMs: input.responseHeadersMs,
+      firstRawEventMs: input.firstRawEventMs,
+      firstMeaningfulEventMs: input.firstMeaningfulEventMs,
+      firstTextEventMs: input.firstTextEventMs,
+      sourceWaitMs: input.sourceWaitMs,
+      forwardingOverheadMs: input.forwardingOverheadMs,
       ...(input.inputTokens === undefined ? {} : { inputTokens: input.inputTokens }),
       ...(input.outputTokens === undefined ? {} : { outputTokens: input.outputTokens }),
       ...(input.totalTokens === undefined ? {} : { totalTokens: input.totalTokens }),

package/src/{kernel/durable-lifecycle.ts → telemetry/subagent-lifecycle.ts}

@@ -2,7 +2,7 @@ import type {
   RuntimeEventConfirmation,
   RuntimeLifecycleFact,
   RuntimeSubagentUsageEvent,
-} from "./submission-authority";
+} from "../tools/subagent-authority";
 
 export interface RuntimeLifecycleSink {
   save(

package/src/telemetry/turn-events.ts

@@ -0,0 +1,279 @@
+import type { AgentHarness, Entry } from "@earendil-works/pi-agent-core";
+import type {
+  RuntimeLifecycleFact,
+  RuntimeModelUsageEvent,
+  RuntimeSubagentUsageEvent,
+  RuntimeToolSettlementEvent,
+  RuntimeTurnEventsPort,
+} from "../config/ports";
+import type { StoredSubmission } from "../submission/repository";
+import { decodeSubagentCompletion, isZeroSubagentUsage, subagentTerminalStatus, type RuntimeSubagentRunMetadata } from "../tools/subagent-runtime";
+import type { RuntimeTelemetryCoordinator } from "./coordinator";
+import { summarizeModelUsage } from "./model-usage";
+import type { RuntimeEventOutboxRepository } from "./runtime-event-repository";
+import { RuntimeSubagentLifecycleRecorder } from "./subagent-lifecycle";
+
+const RETRY_SECONDS = 10;
+const MAX_ATTEMPTS = 5;
+
+type Payload =
+  | { readonly type: "model-usage"; readonly event: RuntimeModelUsageEvent }
+  | { readonly type: "tool-settlement"; readonly event: RuntimeToolSettlementEvent }
+  | { readonly type: "subagent-usage"; readonly event: RuntimeSubagentUsageEvent }
+  | { readonly type: "lifecycle"; readonly event: RuntimeLifecycleFact };
+
+type RequestedModel = Parameters<typeof summarizeModelUsage>[0];
+type SubagentRun = {
+  readonly runId: string;
+  readonly agentType: string;
+  readonly parentToolCallId?: string;
+  readonly startedAt: number;
+  readonly completedAt?: number;
+};
+
+/** Canonical Pi facts become durable Host events; delivery never drives Pi. */
+export class RuntimeTurnEvents {
+  private drainTail?: Promise<void>;
+
+  constructor(private readonly options: {
+    readonly outbox: RuntimeEventOutboxRepository;
+    readonly transaction: <T>(run: () => T) => T;
+    readonly port: () => RuntimeTurnEventsPort | undefined;
+    readonly telemetry: Pick<RuntimeTelemetryCoordinator, "capture">;
+    readonly waitUntil: (promise: Promise<void>) => void;
+    readonly scheduleRetry: (delaySeconds: number, idempotent: boolean) => Promise<void>;
+  }) {}
+
+  private save(payload: Payload, createdAt: number): void {
+    this.options.transaction(() => this.options.outbox.insert({
+      eventId: payload.event.eventId,
+      body: JSON.stringify(payload),
+      createdAt,
+    }));
+  }
+
+  submissionAdmitted(
+    submission: Pick<StoredSubmission, "submissionId" | "requestId" | "createdAt"> & { idempotencyKey?: string | null },
+    hostAccepted: boolean,
+  ): void {
+    if (hostAccepted) this.save({ type: "lifecycle", event: {
+      kind: "submission-admitted",
+      eventId: `${submission.submissionId}:admitted`,
+      submissionId: submission.submissionId,
+      runId: submission.submissionId,
+    } }, submission.createdAt);
+    this.options.telemetry.capture("turnAdmitted", {
+      submissionId: submission.submissionId,
+      requestId: submission.requestId,
+      ...(submission.idempotencyKey ? { idempotencyKey: submission.idempotencyKey } : {}),
+      occurredAt: submission.createdAt,
+    });
+  }
+
+  submissionTerminal(
+    submission: Pick<StoredSubmission, "submissionId" | "runId" | "status"> & { completedAt?: number | null },
+  ): void {
+    if (submission.status === "pending" || submission.status === "running") {
+      throw new Error("Submission terminal fact requires a terminal status");
+    }
+    this.save({ type: "lifecycle", event: {
+      kind: "submission-terminal",
+      eventId: `${submission.submissionId}:terminal`,
+      submissionId: submission.submissionId,
+      runId: submission.runId ?? submission.submissionId,
+      status: submission.status,
+      childRegistrationClosed: true,
+      zeroUsage: !this.options.outbox.hasNonZeroModelUsage(submission.submissionId),
+    } }, submission.completedAt ?? Date.now());
+  }
+
+  private recordEntry(submissionId: string, entry: Entry, model: RequestedModel): void {
+    if (entry.type === "message" && entry.message.role === "assistant") {
+      this.save({ type: "model-usage", event: {
+        eventId: `${submissionId}:model:${entry.id}`,
+        submissionId,
+        runId: submissionId,
+        kind: "assistant",
+        ...summarizeModelUsage(model, [entry.message]),
+      } }, entry.message.timestamp);
+    } else if (entry.type === "message" && entry.message.role === "toolResult") {
+      this.save({ type: "tool-settlement", event: {
+        eventId: `${submissionId}:tool:${entry.message.toolCallId}`,
+        submissionId,
+        toolCallId: entry.message.toolCallId,
+        toolName: entry.message.toolName,
+        status: entry.message.isError ? "error" : "success",
+      } }, entry.message.timestamp);
+    } else if (entry.type === "compaction" || entry.type === "branch_summary") {
+      if (entry.usage) {
+        this.save({ type: "model-usage", event: {
+          eventId: `${submissionId}:compaction:${entry.id}`,
+          submissionId,
+          runId: submissionId,
+          kind: "compaction",
+          api: model.api,
+          provider: model.provider,
+          model: model.id,
+          usage: entry.usage,
+        } }, entry.timestamp);
+      }
+      this.options.telemetry.capture("contextCompacted", {
+        submissionId,
+        compactionId: entry.id,
+        ...(entry.usage ? {
+          inputTokens: entry.usage.input,
+          outputTokens: entry.usage.output,
+        } : {}),
+        summary: entry.summary,
+        occurredAt: entry.timestamp,
+      });
+    }
+  }
+
+  /** Live observation and recovery use exactly the same committed-entry projection. */
+  observe(harness: Pick<AgentHarness, "events">, submissionId: string, model: RequestedModel): void {
+    harness.events.on("entry_added", ({ entry }) => {
+      this.recordEntry(submissionId, entry, model);
+      this.options.waitUntil(this.drain());
+    });
+    harness.events.on("tool_start", (event) => {
+      this.options.telemetry.capture("toolStarted", {
+        submissionId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        input: event.args,
+      });
+    });
+    harness.events.on("tool_end", (event) => {
+      this.options.telemetry.capture("toolFinished", {
+        submissionId,
+        toolCallId: event.toolCallId,
+        toolName: event.toolName,
+        outcome: event.isError ? "failed" : "completed",
+        output: event.result,
+        outputBytes: JSON.stringify(event.result).length,
+      });
+    });
+  }
+
+  backfill(
+    submissionId: string,
+    model: RequestedModel,
+    entries: readonly { readonly entry: Entry; readonly submissionId: string | null }[],
+  ): void {
+    for (const stored of entries) {
+      if (stored.submissionId === submissionId) this.recordEntry(submissionId, stored.entry, model);
+    }
+  }
+
+  private subagentLifecycle(input: { submissionId: string; parentRunId: string }): RuntimeSubagentLifecycleRecorder {
+    return new RuntimeSubagentLifecycleRecorder(input, {
+      save: async (event) => {
+        this.save(event.kind === "subagent"
+          ? { type: "subagent-usage", event }
+          : { type: "lifecycle", event }, Date.now());
+        await this.drain();
+      },
+      has: (eventId) => this.options.outbox.has(eventId),
+      hasSubagentUsage: (submissionId, subagentRunId) =>
+        this.options.outbox.hasSubagentUsage(submissionId, subagentRunId),
+    });
+  }
+
+  async subagentStarted(metadata: RuntimeSubagentRunMetadata, run: SubagentRun): Promise<void> {
+    await this.subagentLifecycle(metadata).register(run.runId);
+    this.options.telemetry.capture("subagentStarted", {
+      submissionId: metadata.submissionId,
+      ...(run.parentToolCallId ? { toolCallId: run.parentToolCallId } : {}),
+      subagentId: run.runId,
+      agentType: run.agentType,
+      occurredAt: run.startedAt,
+    });
+  }
+
+  async subagentFinished(metadata: RuntimeSubagentRunMetadata, run: SubagentRun, result: {
+    readonly status: string;
+    readonly summary?: string;
+    readonly error?: string;
+    readonly childStillRunning?: boolean;
+  }): Promise<void> {
+    const lifecycle = this.subagentLifecycle(metadata);
+    await lifecycle.register(run.runId);
+    if (result.status === "interrupted" && result.childStillRunning) return;
+    const completion = decodeSubagentCompletion(result.summary);
+    const hasUsage = completion && !isZeroSubagentUsage(completion.usage);
+    const status = subagentTerminalStatus(result.status);
+    if (completion && hasUsage) await lifecycle.usage({
+      eventId: `${run.runId}:usage`,
+      submissionId: metadata.submissionId,
+      runId: run.runId,
+      subagentRunId: run.runId,
+      parentRunId: metadata.parentRunId,
+      kind: "subagent",
+      status,
+      usage: completion.usage,
+    });
+    await lifecycle.terminal({ subagentRunId: run.runId, status, zeroUsage: !hasUsage });
+    const occurredAt = run.completedAt ?? Date.now();
+    this.options.telemetry.capture("subagentFinished", {
+      submissionId: metadata.submissionId,
+      ...(run.parentToolCallId ? { toolCallId: run.parentToolCallId } : {}),
+      subagentId: run.runId,
+      outcome: status === "completed" ? "completed"
+        : status === "aborted" || status === "skipped" ? "cancelled" : "failed",
+      durationMs: Math.max(0, occurredAt - run.startedAt),
+      ...(completion ? { output: completion.output } : {}),
+      ...(result.error ? { error: result.error } : {}),
+      occurredAt,
+    });
+  }
+
+  drain(idempotentRetry = true): Promise<void> {
+    const drain = (this.drainTail ?? Promise.resolve())
+      .catch(() => undefined)
+      .then(() => this.deliver(idempotentRetry));
+    this.drainTail = drain;
+    return drain.finally(() => {
+      if (this.drainTail === drain) this.drainTail = undefined;
+    });
+  }
+
+  private async deliver(idempotentRetry: boolean): Promise<void> {
+    const port = this.options.port();
+    if (!port) return;
+    for (const row of this.options.outbox.listPending()) {
+      try {
+        const payload = JSON.parse(row.body) as Payload;
+        if (payload.type === "model-usage") {
+          await port.onModelUsage?.(payload.event);
+        } else if (payload.type === "tool-settlement") {
+          await port.onToolSettled?.(payload.event);
+        } else if (payload.type === "subagent-usage") {
+          if (port.onSubagentUsage && (await port.onSubagentUsage(payload.event))?.confirmed !== true) {
+            throw new Error("Runtime event was not confirmed");
+          }
+        } else if (port.onLifecycleFact && (await port.onLifecycleFact(payload.event))?.confirmed !== true) {
+          throw new Error("Runtime event was not confirmed");
+        }
+        this.options.transaction(() => this.options.outbox.markDelivered(row.eventId, Date.now()));
+      } catch (error) {
+        const failure = error instanceof Error ? error.message : String(error);
+        const attemptCount = this.options.transaction(() => {
+          const count = this.options.outbox.markFailed(row.eventId, failure);
+          if (count >= MAX_ATTEMPTS) this.options.outbox.quarantine(row.eventId, Date.now(), failure);
+          return count;
+        });
+        console.warn(attemptCount >= MAX_ATTEMPTS
+          ? "[runtime-turn-event:quarantined]"
+          : "[runtime-turn-event:degraded]", JSON.stringify({ eventId: row.eventId, attemptCount, error: failure }));
+        if (attemptCount >= MAX_ATTEMPTS) continue;
+        try {
+          await this.options.scheduleRetry(RETRY_SECONDS, idempotentRetry);
+        } catch (error) {
+          console.warn("[runtime-turn-event-retry:degraded]", String(error));
+        }
+        break;
+      }
+    }
+  }
+}

package/src/{pi/tool → tools}/ai-adapter.ts

@@ -7,7 +7,7 @@ import type {
   AgentToolResult,
 } from "@earendil-works/pi-agent-core";
 import { asSchema, type Tool as AiTool } from "ai";
-import { serializeOutput } from "../../lib/artifacts";
+import { serializeOutput } from "../lib/artifacts";
 
 /** 控制一个 ai-sdk Tool 如何投影到 Pi AgentTool。 */
 export interface AiToolAdapterOptions {
@@ -87,7 +87,7 @@ function modelContent(
 /**
  * 把一个可执行的 ai-sdk Tool 转成 Pi AgentTool。
  *
- * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compilePiTools()` 前调用。
+ * Workspace、Skill 和其他 ai-sdk 工具工厂在把候选项交给 `compileHarnessTools()` 前调用。
  *
  * 实现必须在一处同时对齐 schema、execute 参数和结果形状，否则 Pi 的校验、取消信号和 artifact 处理会绕过统一工具边界。
  *

package/src/tools/approval/index.ts

@@ -0,0 +1 @@
+export * from "./repository";

package/src/{db/approval.repo.ts → tools/approval/repository.ts}

@@ -1,5 +1,5 @@
 import type { SqlTaggedTemplate } from "agents/chat";
-import type { ExecutionLevel } from "../lib/execution-level";
+import type { ExecutionLevel } from "../../lib/execution-level";
 
 // Approval 的统一定义见 ./index.ts。
 // #region 状态与行类型
@@ -55,11 +55,6 @@ export interface ApprovalView {
   status: ApprovalStatus;
 }
 
-export interface DecidedApprovalRef {
-  executionId: string;
-  submissionId: string;
-}
-
 type ApprovalRow = {
   execution_id: string;
   submission_id: string;
@@ -105,12 +100,12 @@ function mapRow(row: ApprovalRow): StoredApproval {
 // #region Repository
 export class ApprovalRepository {
   // 保存当前 Agent SQLite 的查询入口。
-  // RuntimeDatabase 构造时调用，ApprovalLifecycle 和 Transcript 随后共享这个 Repository。
+  // RuntimeDatabase 构造时调用，HarnessDecisionGate 和 Transcript 随后共享这个 Repository。
   // Approval 必须与所属 Submission 在同一 Agent 存储中查询，不能跨 Durable Object 拼接状态。
   constructor(private readonly sql: SqlTaggedTemplate) {}
 
   // 按 executionId 读取一条完整 Approval，不存在时返回 null。
-  // ApprovalLifecycle 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
+  // HarnessDecisionGate 在请求去重、决策、继续和拒绝时调用，调用方必须处理 null。
   // execution_id 是主键，LIMIT 1 明确只消费一行；不能改成按非唯一字段随意取首行。
   find(executionId: string): StoredApproval | null {
     const row = this.sql<ApprovalRow>`
@@ -126,7 +121,7 @@ export class ApprovalRepository {
   }
 
   // 持久化一条新的 Approval。
-  // ApprovalLifecycle.ensurePending 在准入事务内确认没有同一记录后调用。
+  // HarnessDecisionGate 在 `before_tool` 事务内确认没有同一记录后调用。
   // 主键和 submission_id/tool_call_id 唯一约束是持久化去重防线，不能用覆盖式 INSERT 掩盖冲突审批。
   insert(approval: NewApproval): void {
     this.sql`
@@ -153,7 +148,7 @@ export class ApprovalRepository {
   }
 
   // 只把 pending Approval 写成指定决策，并记录时间和原因。
-  // applyPiRecoveryMutations 在处理用户决策或恢复命令时调用，迟到的重复决策不应覆盖首次结果。
+  // Runtime 处理用户决策时调用，迟到的重复决策不应覆盖首次结果。
   // WHERE status='pending' 实现首次决策胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
   decide(
     executionId: string,
@@ -172,7 +167,7 @@ export class ApprovalRepository {
   }
 
   // 按创建顺序列出某次 Submission 仍待决策的 executionId。
-  // ApprovalLifecycle.rejectPending 在终止 Turn 时调用，随后为每条待决策记录追加拒绝恢复事实。
+  // Runtime 终止 Turn 时调用，保证没有待决策记录泊留在终态 Submission 上。
   // ORDER BY created_at 保留决策的原始顺序，不能依赖 SQLite 未声明的默认行顺序。
   listPendingForSubmission(submissionId: string): string[] {
     return this.sql<{ execution_id: string }>`
@@ -185,7 +180,7 @@ export class ApprovalRepository {
   }
 
   // 列出所属 Submission 仍活跃的全部待决策 Approval 摘要。
-  // ApprovalLifecycle.list 和广播流程在生成用户可见审批列表时调用。
+  // Runtime 广播流程在生成用户可见审批列表时调用。
   // JOIN Submission 是为了隐藏已终止 Turn 的孤立 pending 行，不能只按 Approval 自身状态暴露给用户。
   listPendingActive(): PendingApprovalSummary[] {
     return this.sql<{
@@ -222,23 +217,8 @@ export class ApprovalRepository {
     }));
   }
 
-  // 按决策时间列出所有已批准或已拒绝的 Approval 引用。
-  // ApprovalLifecycle.dispatchPendingContinuations 在 Runtime 启动时调用，用恢复决策判断哪些记录仍需要继续。
-  // 这里故意不预先猜测“已分派”，幂等性由 Recovery Milestone 决定；不能用内存队列替代跨重启扫描。
-  listDecided(): DecidedApprovalRef[] {
-    return this.sql<{ execution_id: string; submission_id: string }>`
-      SELECT execution_id, submission_id
-      FROM pi_approvals
-      WHERE status IN ('approved', 'rejected')
-      ORDER BY decided_at ASC
-    `.map((row) => ({
-      executionId: row.execution_id,
-      submissionId: row.submission_id,
-    }));
-  }
-
   // 计算所属 Submission 仍活跃的 pending Approval 数量。
-  // ApprovalLifecycle.countPending 在报告交互阻塞和 Runtime 稳定状态时调用。
+  // Runtime 在报告交互阻塞和稳定状态时调用。
   // 与 listPendingActive 使用同样的 JOIN 和状态条件才能保证计数和用户可见列表一致，修改其一时必须核对另一个。
   countPendingActive(): number {
     return (
@@ -254,7 +234,7 @@ export class ApprovalRepository {
   }
 
   // 只在某个 toolCallId 唯一匹配一条活跃 pending Approval 时返回 executionId。
-  // Runtime 处理工具审批决策时通过 ApprovalLifecycle 调用，返回 null 表示没有或存在歧义。
+  // Runtime 处理工具审批决策时通过 HarnessDecisionGate 调用，返回 null 表示没有或存在歧义。
   // toolCallId 只在单个 Submission 内唯一，LIMIT 2 用最小查询识别跨 Submission 重名；不能用 LIMIT 1 静默选中任意 Approval。
   findPendingByToolCallId(toolCallId: string): string | null {
     const matches = this.sql<{ execution_id: string }>`
@@ -274,7 +254,7 @@ export class ApprovalRepository {
 
   // 列出某次 Submission 的审批 ID、工具调用 ID 和状态。
   // Transcript 投影浏览器消息时调用，用这些精简字段补齐工具调用视图。
-  // 这里不返回风险、输入等内容，避免 Transcript 和 ApprovalLifecycle 共享过宽的数据契约。
+  // 这里不返回风险、输入等内容，避免 Transcript 和 HarnessDecisionGate 共享过宽的数据契约。
   listApprovalViews(submissionId: string): ApprovalView[] {
     return this.sql<{
       execution_id: string;