@moretea-labs/forge 1.7.2 → 1.8.1

package/adapters/chatgpt/controller-binding-store.ts

@@ -0,0 +1,134 @@
+import { FORGE_INSTANCE_SCOPE_KEY } from '../../src/cli/repositories/controller-home';
+import { withControllerLock } from '../../src/cli/repositories/locks';
+import { readControlPlaneRecord, writeControlPlaneRecord } from '../../src/runtime/control-plane/persistence/sqlite-store';
+import type { ControllerBinding } from '../../packages/kernel/controller/api/index';
+
+const NAMESPACE = 'chatgpt_controller_binding';
+
+export interface ChatgptControllerBindingPayload {
+  schemaVersion: 1;
+  bindingId: string;
+  /** Optional repository provenance only. */
+  repoId?: string;
+  workId: string;
+  sessionId: string;
+  browserSessionId?: string;
+  conversationUrl?: string;
+  title?: string;
+  model?: string;
+  reasoning?: 'medium' | 'high' | 'xhigh';
+  tabPolicy?: 'auto' | 'reuse' | 'new';
+  timeoutMs?: number;
+  /** Provider transport choice captured by launcher admission; not lifecycle authority. */
+  transportConversation?: 'bound' | 'fresh';
+  /** Initial provider hint captured for the queued ControllerRound only. */
+  continuationPrompt?: string;
+  authorizationGrantRefs?: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export function chatgptControllerProviderBindingId(workId: string): string {
+  return `chatgpt-controller:${workId}`;
+}
+
+function canonicalBindingId(workId: string): string {
+  return chatgptControllerProviderBindingId(workId);
+}
+
+function legacyBindingId(repoId: string, workId: string): string {
+  return `chatgpt-controller:${repoId}:${workId}`;
+}
+
+function readBinding(
+  controllerHome: string,
+  workId: string,
+  repoId?: string,
+): { value: ChatgptControllerBindingPayload; revision: number } | undefined {
+  const canonicalId = canonicalBindingId(workId);
+  const canonical = readControlPlaneRecord<ChatgptControllerBindingPayload>(
+    controllerHome,
+    NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    canonicalId,
+  );
+  const legacy = repoId?.trim()
+    ? readControlPlaneRecord<ChatgptControllerBindingPayload>(
+        controllerHome,
+        NAMESPACE,
+        repoId.trim(),
+        legacyBindingId(repoId.trim(), workId),
+      )
+    : undefined;
+  if (canonical && legacy) {
+    const left = canonical.value;
+    const right = legacy.value;
+    if (left.workId !== right.workId
+      || left.sessionId !== right.sessionId
+      || (left.conversationUrl ?? '') !== (right.conversationUrl ?? '')) {
+      throw new Error(`CHATGPT_CONTROLLER_BINDING_COLLISION: ${workId}`);
+    }
+  }
+  return canonical ?? legacy;
+}
+
+export function upsertChatgptControllerBinding(
+  options: { controllerHome: string; repoId?: string; now?: () => string },
+  input: Omit<ChatgptControllerBindingPayload, 'schemaVersion' | 'bindingId' | 'repoId' | 'createdAt' | 'updatedAt'>,
+): { binding: ControllerBinding; payload: ChatgptControllerBindingPayload } {
+  const id = canonicalBindingId(input.workId);
+  return withControllerLock(
+    options.controllerHome,
+    { scope: 'global', resource: `chatgpt-controller-binding:${input.workId}` },
+    `chatgpt-controller-binding:${id}`,
+    () => {
+      const current = readBinding(options.controllerHome, input.workId, options.repoId);
+      const at = options.now?.() ?? new Date().toISOString();
+      const payload: ChatgptControllerBindingPayload = {
+        ...(current?.value ?? {} as ChatgptControllerBindingPayload),
+        ...input,
+        schemaVersion: 1,
+        bindingId: id,
+        ...(options.repoId?.trim() ? { repoId: options.repoId.trim() } : {}),
+        createdAt: current?.value.createdAt ?? at,
+        updatedAt: at,
+      };
+      writeControlPlaneRecord(options.controllerHome, {
+        namespace: NAMESPACE,
+        scope: FORGE_INSTANCE_SCOPE_KEY,
+        key: id,
+        schemaVersion: 1,
+        value: payload,
+        action: current ? 'chatgpt_controller_binding_update' : 'chatgpt_controller_binding_create',
+        expectedRevision: readControlPlaneRecord<ChatgptControllerBindingPayload>(
+          options.controllerHome,
+          NAMESPACE,
+          FORGE_INSTANCE_SCOPE_KEY,
+          id,
+        )?.revision ?? null,
+      });
+      return { binding: { bindingId: id, hostKind: 'chatgpt', adapterRef: id }, payload };
+    },
+  );
+}
+
+export function getChatgptControllerBindingPayload(
+  options: { controllerHome: string; repoId?: string },
+  adapterRef: string,
+): ChatgptControllerBindingPayload | undefined {
+  const canonical = readControlPlaneRecord<ChatgptControllerBindingPayload>(
+    options.controllerHome,
+    NAMESPACE,
+    FORGE_INSTANCE_SCOPE_KEY,
+    adapterRef,
+  )?.value;
+  if (canonical) return canonical;
+  const repoId = options.repoId?.trim();
+  if (!repoId) return undefined;
+  return readControlPlaneRecord<ChatgptControllerBindingPayload>(
+    options.controllerHome,
+    NAMESPACE,
+    repoId,
+    adapterRef,
+  )?.value;
+}

package/adapters/chatgpt/controller-round-host.ts

@@ -0,0 +1,68 @@
+import {
+  readControllerRoundContextSnapshot,
+  type ControllerRoundRelayRecord,
+  type ControllerRoundRelayStoreOptions,
+} from '../../packages/kernel/controller/api/index';
+import { hasChatgptConversationIdentity, type ChatgptWorkConversationBinding } from './work-conversation-binding-store';
+
+/** ChatGPT-specific rendering of one provider-neutral Kernel ControllerRound. */
+export function buildChatgptControllerRoundPrompt(
+  options: ControllerRoundRelayStoreOptions,
+  record: ControllerRoundRelayRecord,
+  promptOptions: { exactOriginWork?: boolean } = {},
+): string {
+  const snapshot = readControllerRoundContextSnapshot(options, record);
+  const requirementLine = snapshot.requirement
+    ? `Requirement ${snapshot.requirement.requirementId}：state=${snapshot.requirement.state}；outcome=${snapshot.requirement.outcomeStatement}`
+    : '当前未绑定 durable Requirement。';
+  const workLines = snapshot.works.length > 0
+    ? snapshot.works.map((work) => {
+      const summary = `- ${work.workId}：updated=${work.updatedAt}；objective=${work.objective}`;
+      if (work.workId !== snapshot.originWorkId || work.acceptanceCriteria.length === 0) return summary;
+      return [
+        summary,
+        '  origin Work acceptanceCriteria：',
+        ...work.acceptanceCriteria.map((criterion, index) => `  ${index + 1}. ${criterion}`),
+      ].join('\n');
+    }).join('\n')
+    : '- 未找到关联 Work 快照';
+  const originWork = snapshot.works.find((work) => work.workId === snapshot.originWorkId);
+  const terminalOriginGuidance = originWork?.state === 'completed'
+    ? `origin Work ${snapshot.originWorkId} 的持久状态已完成。不要重新打开它；重新读取 Requirement/Plan/Work 语义事实，由模型决定是否仍有新的明确工作。`
+    : undefined;
+  const handoffLines = snapshot.handoffs.length > 0
+    ? snapshot.handoffs.map((handoff) => `- ${handoff.id}：status=${handoff.status}；work=${handoff.workId ?? 'repo'}；${handoff.title}；reason=${handoff.reason}`).join('\n')
+    : '- 当前没有 active linked Handoff';
+  return [
+    `继续 Forge ${snapshot.requirement ? `Requirement ${snapshot.requirement.requirementId}` : `Work ${snapshot.originWorkId}`}，repo=${snapshot.repoId}。`,
+    '下面快照来自本轮 claim-time durable state，用它直接恢复上下文。只有某个事实的新鲜度会实质改变下一次具体 domain action 时，才针对性重新读取；不要把本轮先消耗在重复读取 Requirement/Plan/Work/UserRequest 或 lifecycle bookkeeping 上。',
+    requirementLine,
+    `关联 Work 快照：\n${workLines}`,
+    'origin Work 的 objective 与 acceptanceCriteria 是需要显式检查的 durable semantic contract；语义结论只来自最新事实与模型判断。',
+    `Active Handoff 快照：\n${handoffLines}`,
+    ...(snapshot.assistantContext ? [snapshot.assistantContext] : []),
+    ...(snapshot.executionQualitySignals?.length ? [
+      `Execution quality evidence (advisory): ${JSON.stringify(snapshot.executionQualitySignals)}`,
+      'Review this evidence before repeating the same operation. Diagnose semantically; record whether an adjustment is justified. Do not infer a bug from edit counts, discard mandatory checks, widen authority or create another supervisor.',
+    ] : []),
+    promptOptions.exactOriginWork
+      ? `只推进 origin Work ${snapshot.originWorkId} 的既定范围。若存在真实用户授权/判断 blocker，记录一个去重的 UserRequest；否则继续可执行工作。`
+      : `origin Work 是 ${snapshot.originWorkId}。不要假设下一步必须继续它；依据最新 semantic state 选择现有或新的明确 Work。`,
+    ...(terminalOriginGuidance ? [terminalOriginGuidance] : []),
+    'Provider/session binding、transport recovery、dedupe、retry 和 continuation bookkeeping 由 Forge 内部维护，不属于模型工作流，也不是 Requirement/Plan/Work 的第二套语义权威。',
+    '执行与验证直接使用当前 domain capability；只有 durable 语义实际变化时才更新 Requirement/Plan/Work。Forge 不替模型推断语义 next step。',
+    '如果 origin Work 尚未完成且没有真实 UserRequest/外部 blocker，本轮结束前必须完成至少一个直接推进 objective 的具体 domain action，例如源码修改、进程/检查、typed external effect，或对实现决策有实质作用的源码调查。仅汇报状态、重复读取 lifecycle、刷新进度或说明“下一步要做什么”不算推进。',
+    '仓库工程、安全、权限和资源 fence 始终有效。若真实外部条件或用户判断阻塞，记录精确 UserRequest/Handoff；不要为了机械续跑创建 sibling Work、PlanStep 或额外 lifecycle。',
+    'Presentation-only progress：持续较久或包含多轮工具调用时，在关键阶段用 1–2 句 user-visible 进度说明已确认结果、下一件事或真实 blocker。不要逐工具播报，不要输出 private reasoning / chain-of-thought。',
+  ].join('\n');
+}
+
+/** ChatGPT adapter continuity proof; Kernel only sees the opaque binding id. */
+export function chatgptControllerRoundBindingAuthorizesRecovery(
+  record: ControllerRoundRelayRecord | undefined,
+  binding: ChatgptWorkConversationBinding | undefined,
+): boolean {
+  if (record?.controllerType !== 'chatgpt' || record.status !== 'dispatched' || !record.bindingId || !binding) return false;
+  if (binding.bindingId !== record.bindingId || !binding.latestBrowserSessionId) return false;
+  try { return hasChatgptConversationIdentity(binding.conversationUrl); } catch { return false; }
+}

package/adapters/chatgpt/controller-round-settlement-store.ts

@@ -0,0 +1,99 @@
+import { createHash } from 'crypto';
+import { withControllerLock } from '../../src/cli/repositories/locks';
+import { readControlPlaneRecord, writeControlPlaneRecord } from '../../src/runtime/control-plane/persistence/sqlite-store';
+
+// Resource-cleanup evidence only. Autonomous outer-turn dispatch authority is the Workflow Supervisor Effect ledger; ControllerRound fields are lower-layer/bootstrap compatibility mirrors.
+const NAMESPACE = 'chatgpt_controller_round_settlement';
+
+export type ChatgptControllerRoundSettlementStatus =
+  | 'round_open'
+  | 'retained_for_immediate_continuation'
+  | 'closed'
+  | 'preserved_user_owned'
+  | 'session_closed'
+  | 'failed';
+
+/** Browser/tab resource settlement evidence after a semantic ControllerRound; never proof that a provider prompt was dispatched. */
+export interface ChatgptControllerRoundSettlement {
+  schemaVersion: 1;
+  repoId: string;
+  workId: string;
+  relayScopeId: string;
+  status: ChatgptControllerRoundSettlementStatus;
+  recordedAt: string;
+  error?: string;
+  /**
+   * Opaque identity of the browser resource and grants used for this settlement
+   * attempt. A matching failed attempt must not repeatedly call the provider.
+   */
+  attemptIdentity?: string;
+}
+
+function settlementKey(workId: string, relayScopeId: string): string {
+  return `${workId}:${relayScopeId}`;
+}
+
+/**
+ * Keep browser-session and grant identifiers out of durable settlement evidence
+ * while preserving the exact retry boundary: a changed session or grant set may
+ * be retried, an unchanged failed attempt may not.
+ */
+export function chatgptControllerRoundSettlementAttemptIdentity(input: {
+  browserSessionId: string;
+  authorizationGrantRefs?: readonly string[];
+}): string {
+  const identity = {
+    browserSessionId: input.browserSessionId.trim(),
+    authorizationGrantRefs: [...new Set((input.authorizationGrantRefs ?? [])
+      .map((grantRef) => grantRef.trim())
+      .filter(Boolean))].sort(),
+  };
+  return `sha256:${createHash('sha256').update(JSON.stringify(identity)).digest('hex')}`;
+}
+
+export function getChatgptControllerRoundSettlement(
+  options: { controllerHome: string; repoId: string },
+  input: { workId: string; relayScopeId: string },
+): ChatgptControllerRoundSettlement | undefined {
+  return readControlPlaneRecord<ChatgptControllerRoundSettlement>(
+    options.controllerHome,
+    NAMESPACE,
+    options.repoId,
+    settlementKey(input.workId, input.relayScopeId),
+  )?.value;
+}
+
+export function recordChatgptControllerRoundSettlement(
+  options: { controllerHome: string; repoId: string; now?: () => string },
+  input: {
+    workId: string;
+    relayScopeId: string;
+    status: ChatgptControllerRoundSettlementStatus;
+    error?: string;
+    attemptIdentity?: string;
+  },
+): ChatgptControllerRoundSettlement {
+  const key = settlementKey(input.workId, input.relayScopeId);
+  return withControllerLock(options.controllerHome, { scope: 'task', repoId: options.repoId, taskId: `chatgpt-round-settlement-${input.workId}` }, `chatgpt-round-settlement:${key}`, () => {
+    const existing = readControlPlaneRecord<ChatgptControllerRoundSettlement>(options.controllerHome, NAMESPACE, options.repoId, key);
+    const error = input.error?.trim().slice(0, 2_000) || undefined;
+    const attemptIdentity = input.attemptIdentity?.trim().slice(0, 200) || undefined;
+    if (
+      existing?.value.status === input.status
+      && existing.value.error === error
+      && existing.value.attemptIdentity === attemptIdentity
+    ) return existing.value;
+    const value: ChatgptControllerRoundSettlement = {
+      schemaVersion: 1,
+      repoId: options.repoId,
+      workId: input.workId,
+      relayScopeId: input.relayScopeId,
+      status: input.status,
+      recordedAt: options.now?.() ?? new Date().toISOString(),
+      ...(error ? { error } : {}),
+      ...(attemptIdentity ? { attemptIdentity } : {}),
+    };
+    writeControlPlaneRecord(options.controllerHome, { namespace: NAMESPACE, scope: options.repoId, key, schemaVersion: 1, value, action: 'chatgpt_controller_round_settlement', expectedRevision: existing?.revision ?? null });
+    return value;
+  });
+}

package/adapters/chatgpt/provider-delivery.ts

@@ -0,0 +1,340 @@
+import { createHash } from 'crypto';
+
+export const DEFAULT_CHATGPT_AUTOMATION_MODEL = 'gpt-5.6';
+export const DEFAULT_CHATGPT_AUTOMATION_REASONING = 'high';
+export const DEFAULT_CHATGPT_AUTOMATION_TAB_POLICY = 'auto';
+export const CHATGPT_AUTOMATION_SUBMISSION_OUTCOME_UNKNOWN = 'CHATGPT_AUTOMATION_SUBMISSION_OUTCOME_UNKNOWN';
+export const CHATGPT_AUTOMATION_MESSAGE_DELIVERY_TIMED_OUT = 'CHATGPT_AUTOMATION_MESSAGE_DELIVERY_TIMED_OUT';
+export const CHATGPT_AUTOMATION_RESPONSE_STREAM_UNAVAILABLE = 'CHATGPT_AUTOMATION_RESPONSE_STREAM_UNAVAILABLE';
+export const CHATGPT_AUTOMATION_RATE_LIMITED = 'CHATGPT_AUTOMATION_RATE_LIMITED';
+export const CHATGPT_AUTOMATION_RATE_LIMITED_AFTER_SUBMIT = 'CHATGPT_AUTOMATION_RATE_LIMITED_AFTER_SUBMIT';
+export const CHATGPT_AUTOMATION_CONVERSATION_LIMIT_REACHED = 'CHATGPT_AUTOMATION_CONVERSATION_LIMIT_REACHED';
+
+export type ChatgptProviderPageFailureCode =
+  | typeof CHATGPT_AUTOMATION_MESSAGE_DELIVERY_TIMED_OUT
+  | typeof CHATGPT_AUTOMATION_RESPONSE_STREAM_UNAVAILABLE
+  | typeof CHATGPT_AUTOMATION_RATE_LIMITED
+  | typeof CHATGPT_AUTOMATION_CONVERSATION_LIMIT_REACHED;
+
+function normalizeChatgptProviderPageText(value: string): string {
+  return value.replace(/\s+/g, ' ').trim().toLowerCase();
+}
+
+/** Shared provider-page failure detection used by both direct delivery and durable Supervisor observation. */
+export function chatgptProviderPageFailure(
+  bodyText: string | undefined,
+): ChatgptProviderPageFailureCode | undefined {
+  const normalized = normalizeChatgptProviderPageText(bodyText ?? '');
+  // Dedicated live provider-status text only. Callers must not pass an
+  // unrestricted historical conversation transcript into this classifier.
+  if (normalized.includes('你已达到此对话的长度上限')
+    || normalized.includes('此对话已达到长度上限')
+    || normalized.includes('you have reached the maximum length for this conversation')
+    || normalized.includes("you've reached the maximum length for this conversation")
+    || normalized.includes('this conversation has reached its maximum length')
+    || normalized.includes('you have reached the conversation length limit')) {
+    return CHATGPT_AUTOMATION_CONVERSATION_LIMIT_REACHED;
+  }
+  if (
+    normalized.includes('resume stream unavailable')
+    || normalized.includes('tokenless_resume_unavailable')
+    || normalized.includes('stream recovery polling timed out')
+    || normalized.includes('连接已中断，正在等待完整答复')
+    || normalized.includes('connection interrupted, waiting for the full response')
+    || (normalized.includes('出了点问题') && normalized.includes('请重试'))
+    // A standalone current status is termination evidence. The same words in
+    // ordinary chat prose or a historical whole-page transcript are not.
+    || /^(?:已分析\s+)?(?:分析已暂停|analysis paused)(?:\s+(?:分析已暂停|analysis paused))*$/.test(normalized)
+  ) {
+    return CHATGPT_AUTOMATION_RESPONSE_STREAM_UNAVAILABLE;
+  }
+  if (
+    normalized.includes('too many requests')
+    || normalized.includes('rate limit exceeded')
+    || (normalized.includes('http 429') && normalized.includes('rate limit'))
+  ) {
+    return CHATGPT_AUTOMATION_RATE_LIMITED;
+  }
+  return ((normalized.includes('message delivery timed out') && normalized.includes('please try again'))
+    || (normalized.includes('消息传输超时') && normalized.includes('请重试')))
+    ? CHATGPT_AUTOMATION_MESSAGE_DELIVERY_TIMED_OUT
+    : undefined;
+}
+
+export type ChatgptAutomationReasoning = 'medium' | 'high' | 'xhigh';
+export type ChatgptAutomationTabPolicy = 'auto' | 'reuse' | 'new';
+export type ChatgptAutomationTabCleanupStatus = 'closed' | 'preserved_user_owned' | 'session_closed' | 'failed';
+
+export type ChatgptProviderFailureDisposition = 'outcome_unknown' | 'wait_for_user' | 'failed';
+export type ChatgptProviderDeliveryStatus = 'dispatch_confirmed' | ChatgptProviderFailureDisposition;
+export type ChatgptProviderKind = 'controller-browser' | 'chatgpt-bridge';
+
+export class ChatgptProviderDeliveryError extends Error {
+  readonly code: string;
+  readonly conversationUrl?: string;
+
+  constructor(code: string, message: string, options: { conversationUrl?: string } = {}) {
+    super(message);
+    this.name = 'ChatgptProviderDeliveryError';
+    this.code = code;
+    this.conversationUrl = options.conversationUrl;
+  }
+}
+
+export interface ChatgptProviderErrorEvidence {
+  code: string;
+  message: string;
+  conversationUrl?: string;
+}
+
+export interface ChatgptProviderDeliveryInput {
+  controllerHome: string;
+  repoId: string;
+  repoRoot: string;
+  workId: string;
+  prompt: string;
+  browserSessionId: string;
+  targetUrl: string;
+  model: string;
+  reasoning: 'medium' | 'high' | 'xhigh';
+  timeoutMs?: number;
+}
+
+export interface ChatgptProviderDeliveryResult {
+  status: ChatgptProviderDeliveryStatus;
+  provider: ChatgptProviderKind;
+  browserSessionId: string;
+  conversationUrl?: string;
+  executionPreferenceVerified: boolean;
+  error?: { code: string; message: string };
+}
+
+/** Provider delivery owns browser/bridge mutation and confirmation, never semantic Work authority. */
+export interface ChatgptProviderDeliveryHost {
+  dispatch(input: ChatgptProviderDeliveryInput): Promise<ChatgptProviderDeliveryResult>;
+}
+
+interface ChatgptProviderDispatchGate {
+  tail: Promise<void>;
+  queued: number;
+  pressureLevel: number;
+  cooldownUntilMs: number;
+}
+
+const CHATGPT_PROVIDER_BACKPRESSURE_BASE_MS = 2_000;
+const CHATGPT_PROVIDER_BACKPRESSURE_MAX_MS = 30_000;
+const CHATGPT_PROVIDER_EXPLICIT_RETRY_MAX_MS = 120_000;
+const chatgptProviderDispatchGates = new Map<string, ChatgptProviderDispatchGate>();
+
+function providerGateKey(controllerHome: string): string {
+  return controllerHome.trim() || 'forge-controller';
+}
+
+function chatgptProviderDispatchGate(controllerHome: string): ChatgptProviderDispatchGate {
+  const key = providerGateKey(controllerHome);
+  let gate = chatgptProviderDispatchGates.get(key);
+  if (!gate) {
+    gate = { tail: Promise.resolve(), queued: 0, pressureLevel: 0, cooldownUntilMs: 0 };
+    chatgptProviderDispatchGates.set(key, gate);
+  }
+  return gate;
+}
+
+function retryAfterDelayMs(message: string | undefined): number | undefined {
+  if (!message) return undefined;
+  const match = message.match(/\bretry[- ]?after\s*[:=]?\s*(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|sec(?:ond)?s?)?\b/i);
+  if (!match) return undefined;
+  const amount = Number(match[1]);
+  if (!Number.isFinite(amount) || amount <= 0) return undefined;
+  const milliseconds = match[2]?.toLowerCase().startsWith('m') ? amount : amount * 1_000;
+  return Math.max(1_000, Math.min(CHATGPT_PROVIDER_EXPLICIT_RETRY_MAX_MS, Math.round(milliseconds)));
+}
+
+/** Deterministic jitter keeps concurrent callers from reconverging on one provider boundary after cooldown. */
+export function chatgptProviderBackoffDelayMs(
+  pressureLevel: number,
+  key = 'chatgpt',
+  message?: string,
+): number {
+  const explicit = retryAfterDelayMs(message);
+  if (explicit !== undefined) return explicit;
+  const exponent = Math.max(0, Math.min(8, Math.trunc(pressureLevel) - 1));
+  const base = Math.min(CHATGPT_PROVIDER_BACKPRESSURE_MAX_MS, CHATGPT_PROVIDER_BACKPRESSURE_BASE_MS * 2 ** exponent);
+  const jitterByte = createHash('sha256').update(`${key}\n${pressureLevel}`).digest()[0] ?? 128;
+  const jitter = 0.8 + (jitterByte / 255) * 0.4;
+  return Math.max(1_000, Math.min(CHATGPT_PROVIDER_BACKPRESSURE_MAX_MS, Math.round(base * jitter)));
+}
+
+export function chatgptProviderFailureRequiresBackpressure(
+  status: ChatgptProviderDeliveryStatus | undefined,
+  code?: string,
+  message?: string,
+): boolean {
+  if (status === 'outcome_unknown') return true;
+  const normalized = `${code ?? ''}\n${message ?? ''}`.toUpperCase();
+  return normalized.includes('RATE_LIMITED')
+    || normalized.includes('TOO MANY REQUESTS')
+    || normalized.includes('HTTP 429')
+    || normalized.includes('TOKENLESS_RESUME_UNAVAILABLE')
+    || normalized.includes('RESPONSE_STREAM_UNAVAILABLE')
+    || normalized.includes('MESSAGE_DELIVERY_TIMED_OUT');
+}
+
+export function noteChatgptProviderBackpressure(
+  controllerHome: string,
+  message?: string,
+  nowMs = Date.now(),
+): number {
+  const key = providerGateKey(controllerHome);
+  const gate = chatgptProviderDispatchGate(controllerHome);
+  gate.pressureLevel += 1;
+  const delayMs = chatgptProviderBackoffDelayMs(gate.pressureLevel, key, message);
+  gate.cooldownUntilMs = Math.max(gate.cooldownUntilMs, nowMs + delayMs);
+  return delayMs;
+}
+
+export function chatgptProviderBackpressureRemainingMs(
+  controllerHome: string,
+  nowMs = Date.now(),
+): number {
+  const gate = chatgptProviderDispatchGates.get(providerGateKey(controllerHome));
+  return gate ? Math.max(0, gate.cooldownUntilMs - nowMs) : 0;
+}
+
+export interface ChatgptProviderDispatchOutcome {
+  status?: ChatgptProviderDeliveryStatus;
+  code?: string;
+  message?: string;
+  /**
+   * True only when the provider actually accepted this submission. A local
+   * transport failure (foreground required, composer missing, transport
+   * unavailable) is neither acceptance nor provider backpressure, so it must
+   * not clear pressure that a real provider limit established.
+   */
+  providerAccepted?: boolean;
+}
+
+/**
+ * One active Runtime owns one transient ChatGPT provider dispatch lane. This is
+ * deliberately mechanical and in-memory: ControllerRound effect identity remains
+ * the durable replay fence across Runtime rotation, while provider pressure must
+ * not become Work/Plan lifecycle state.
+ *
+ * Provider rate limiting is an account-level resource, so *every* transport that
+ * can submit a provider prompt through this Runtime must enter the same lane and
+ * obey the same cooldown. A separate lane that only reads the cooldown still
+ * submits concurrently with this one, which is exactly how one ChatGPT account
+ * observes request concurrency that no single session produced.
+ */
+export async function withChatgptProviderDispatchLane<T>(
+  controllerHome: string,
+  operation: () => Promise<T>,
+  outcomeOf: (result: T) => ChatgptProviderDispatchOutcome | undefined,
+): Promise<T> {
+  const key = providerGateKey(controllerHome);
+  const gate = chatgptProviderDispatchGate(controllerHome);
+
+  const predecessor = gate.tail;
+  let release!: () => void;
+  gate.tail = new Promise<void>((resolve) => { release = resolve; });
+  gate.queued += 1;
+  await predecessor;
+
+  try {
+    const waitMs = gate.cooldownUntilMs - Date.now();
+    if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+
+    const result = await operation();
+    const outcome = outcomeOf(result);
+    if (outcome && chatgptProviderFailureRequiresBackpressure(outcome.status, outcome.code, outcome.message)) {
+      noteChatgptProviderBackpressure(controllerHome, outcome.message);
+    } else if (outcome?.providerAccepted === true) {
+      gate.pressureLevel = 0;
+      gate.cooldownUntilMs = 0;
+    }
+    return result;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (chatgptProviderFailureRequiresBackpressure(undefined, undefined, message)) {
+      noteChatgptProviderBackpressure(controllerHome, message);
+    }
+    throw error;
+  } finally {
+    gate.queued -= 1;
+    release();
+    if (gate.queued === 0 && gate.pressureLevel === 0 && gate.cooldownUntilMs <= Date.now()) {
+      chatgptProviderDispatchGates.delete(key);
+    }
+  }
+}
+
+/** Controller-relay delivery: one serialized provider prompt submission lane. */
+export async function dispatchWithChatgptProviderBackpressure(
+  controllerHome: string,
+  dispatch: () => Promise<ChatgptProviderDeliveryResult>,
+): Promise<ChatgptProviderDeliveryResult> {
+  return await withChatgptProviderDispatchLane(controllerHome, dispatch, (result) => (
+    chatgptProviderFailureRequiresBackpressure(result.status, result.error?.code, result.error?.message)
+      ? { code: result.error?.code, message: result.error?.message }
+      : { providerAccepted: result.status === 'dispatch_confirmed' }
+  ));
+}
+
+const CHATGPT_WAIT_FOR_USER_MARKERS = [
+  'LOGIN_REQUIRED',
+  'AUTH_REQUIRED',
+  'AUTHENTICATION_REQUIRED',
+  'USER_ACTION_REQUIRED',
+  'PERMISSION_REQUIRED',
+  'CONSENT_REQUIRED',
+] as const;
+
+/** Classify provider failure without turning delivery/session details into Kernel authority. */
+export function classifyChatgptProviderFailure(
+  code?: string,
+  message?: string,
+): ChatgptProviderFailureDisposition {
+  const normalized = `${code ?? ''}\n${message ?? ''}`.toUpperCase();
+  if (
+    normalized.includes('OUTCOME_UNKNOWN')
+    || normalized.includes('MESSAGE_DELIVERY_TIMED_OUT')
+    || normalized.includes('RESPONSE_STREAM_UNAVAILABLE')
+    || normalized.includes('RATE_LIMITED_AFTER_SUBMIT')
+  ) return 'outcome_unknown';
+  if (CHATGPT_WAIT_FOR_USER_MARKERS.some((marker) => normalized.includes(marker))) return 'wait_for_user';
+  return 'failed';
+}
+
+
+export function chatgptProviderDispatchReceiptId(input: {
+  repoId: string;
+  workId: string;
+  relayScopeId: string;
+  controllerAuthorityId: string;
+  provider: ChatgptProviderKind;
+}): string {
+  const digest = createHash('sha256').update([
+    input.repoId,
+    input.workId,
+    input.relayScopeId,
+    input.controllerAuthorityId,
+    input.provider,
+  ].join('\n')).digest('hex').slice(0, 32);
+  return `chatgpt-dispatch:${digest}`;
+}
+
+export function chatgptProviderError(error: unknown, fallbackCode: string): ChatgptProviderErrorEvidence {
+  const message = error instanceof Error ? error.message : String(error);
+  const code = error instanceof ChatgptProviderDeliveryError
+    ? error.code
+    : error instanceof Error && error.message.includes(':')
+      ? error.message.split(':', 1)[0]
+      : fallbackCode;
+  return {
+    code,
+    message,
+    ...(error instanceof ChatgptProviderDeliveryError && error.conversationUrl
+      ? { conversationUrl: error.conversationUrl }
+      : {}),
+  };
+}