@zhushanwen/pi-structured-output 5.1.8 → 6.0.0

package/README.md

@@ -0,0 +1,85 @@
+# @zhushanwen/pi-structured-output
+
+结构化输出 pi extension：让模型用经过 JSON Schema 校验的工具调用代替自由文本交付结果。按 `PI_WORKFLOW_SCHEMA` 环境变量装配两种变体——workflow 模式以引擎注入的权威 schema 强制约束产出，日常模式校验模型自报 schema 的数据。
+
+## 两种模式
+
+启动时读取 `PI_WORKFLOW_SCHEMA`（该 env 由 subagent workflow 引擎注入子进程）：
+
+| | workflow 模式（env 有值） | 日常模式（env 无值） |
+|---|---|---|
+| 工具参数 | 单参数——parameters 即权威 schema 本身 | 双参数 `{schema, data}` 自报形态 |
+| 校验权威 | pi 参数层直接按权威 schema 校验模型 arguments，execute 透传不二次校验 | Ajv 校验自报 data（防御链见下） |
+| 强制手段 | turn_end 未成功调用工具（完全未调用，或调用了但全部校验失败）→ steer 注入重试（整个子进程生命周期最多 2 次）；同签名失败连续 3 次 → 写日志后 abort 当前 turn + shutdown 子进程，15s 内未退出则进程硬退兜底 | 无（普通工具，失败抛错由模型自修） |
+
+## 提供的工具
+
+### `structured-output`
+
+**workflow 模式**（`PI_WORKFLOW_SCHEMA` 有值时注册）：
+
+- object 根 schema：arguments 即数据本身，如 `structured-output({ score: 8 })`
+- 非 object 根 schema（array/string/number/boolean/组合根等）：包装为 `{ value: <data> }`（tool call arguments 协议上必须是 object），错误路径带 `value.` 前缀
+- 根级 `additionalProperties` 未声明时注入 `false`：模型多传的字段被参数层显式拒绝（作者显式声明则尊重不动）
+- 注册期 fail-fast：非法 schema（非 object/boolean 根、boolean true、无任何关键字的 object）在子进程加载期即终止并指回 workflow 脚本的 schema 定义；schema 超 256KiB 时 stderr 提示精简/拆分（硬拒绝在引擎注入侧）
+
+**日常模式**（交互式 pi 注册）：
+
+- `schema`：JSON Schema draft-07 对象
+- `data`：待校验的值（原始类型/object/array 均可）
+
+日常模式防御链（编译前拦截，全部抛错并带回显与纠错提示）：
+
+1. 互换检测——schema 像数据且 data 像 schema → 判定为参数装反，拒绝
+2. 无关键字 schema 拒绝——`{}` / `{a:1}` 会被 Ajv（`strict:false`）编译成"接受一切"，静默放行垃圾数据
+3. Ajv 编译失败 → 报 Invalid JSON Schema
+4. 校验失败 → 报告失败字段路径
+
+## 安装
+
+```bash
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-structured-output
+
+# 本地路径加载（开发调试；-e 为 --extension 简写，可多次传入）
+pi -e /path/to/extensions/universal/structured-output
+pi --extension /path/to/extensions/universal/structured-output
+```
+
+## 示例
+
+日常模式（模型自报 schema + data）：
+
+```
+structured-output({
+  schema: { type: "object", properties: { score: { type: "number" } }, required: ["score"] },
+  data: { score: 8 }
+})
+```
+
+workflow 模式（schema 由引擎注入，模型只提交数据）：
+
+```
+structured-output({ score: 8 })            # object 根：arguments 即数据
+structured-output({ value: [1, 2, 3] })    # array 根：包装在 value 字段
+```
+
+## 文件结构
+
+```
+structured-output/
+├── index.ts            # 入口 — re-export src/index.ts
+└── src/
+    ├── index.ts            # 装配分岔：读 PI_WORKFLOW_SCHEMA 选择变体 + re-export
+    ├── tool-definition.ts  # 双变体工具定义（workflow 单参数 / 日常双参数）
+    ├── execute.ts          # 校验编排（workflow 透传 / 日常防御链）+ 根形态判定
+    ├── ajv-validator.ts    # Ajv 编译缓存（WeakMap）
+    ├── schema-guards.ts    # 形态守卫纯函数（互换检测 / 关键字识别 / JSON 解析回显）
+    ├── workflow-hook.ts    # turn_end 强制调用 hook + RetryState 状态机
+    ├── loop-gate.ts        # 同签名失败 ×3 有界闸门（abort + shutdown + 硬退兜底）
+    └── text-primitives.ts  # 截断/错误块有界化共享原语
+```
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-structured-output",
-  "version": "5.1.8",
+  "version": "6.0.0",
   "description": "Structured output tool for Pi — workflow schema enforcement via pi's parameter layer; interactive mode validates self-reported schemas with Ajv",
   "type": "module",
   "main": "index.ts",
@@ -25,7 +25,7 @@
   ],
   "dependencies": {
     "ajv": "^8.17.0",
-    "@zhushanwen/pi-ext-guards": "0.4.1"
+    "@zhushanwen/pi-ext-guards": "0.4.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",

package/src/index.ts

@@ -4,32 +4,26 @@
  * 装配分岔（D1，U1）：读 PI_WORKFLOW_SCHEMA——
  *   - 有值（workflow 子进程）：注册 workflow 变体（parameters = 权威 schema 本身，
  *     D4 根级 additionalProperties 注入 / P6 非 object 根 {value} 包装 / 注册期
- *     fail-fast 防御都在 createWorkflowToolDefinition 内）+ turn_end 强制 hook
+ *     fail-fast 防御都在 createWorkflowToolDefinition 内）+ 双闸门合一 hook
  *   - 无值（日常 pi）：注册日常变体（双参数自报形态，行为不变，G4）
  *
- * Hook 机制（仅 workflow 模式）：
- *   turn_end 时检查模型是否调用了 structured-output 工具。
- *   如果没调 → 通过 pi.sendUserMessage() 注入 steering message 强制调用。
- *   最多重试 2 次，防止无限循环。
+ * Hook 机制（仅 workflow 模式，D2 单状态机单 listener）：
+ *   turn_end 时检查模型是否调用了 structured-output 工具，没调/失败则 steer 注入
+ *   重试提醒（软闸门，最多重试 2 次）。同一状态机（WorkflowGate）上的硬杀闸门在
+ *   同签名校验失败达 3 次时 terminal：写日志（stderr + session JSONL 双通道，含恢复
+ *   指引）后 ctx.abort() + ctx.shutdown() 优雅终止子进程 + 15s 兜底硬退 timer——
+ *   terminal 后软闸门不再 steer（同一份 terminal 事实，无跨对象接线；G2 与模型
+ *   配合度无关）。装配与 listener 明细见 workflow-hook.setupWorkflowHook。
  *
- * 失败闸门（仅 workflow 模式，D3/U2）：
- *   tool_execution_end 上计数同签名校验失败，连续 3 次 → terminal：写日志
- *   （stderr + session JSONL 双通道，含恢复指引）后 ctx.abort()（停当前 turn）+
- *   ctx.shutdown() 优雅终止子进程（RPC mode 于 agent_settled 后 exit），并武装
- *   15s 兑底硬退 timer（R3 F-2 bounded teardown：pi 0.84.1 ExtensionAPI 无子进程
- *   信号能力，扩展与子进程同进程，process.exit 是唯一硬杀手段；覆盖 shutdown
- *   请求后 pi 挂死不 settle 的异常态）；同时标记 RetryState.terminal，turn_end
- *   hook 不再 steer。
- *
- * 模块拆分（M4）：实现体分布于 ajv-validator.ts（编译缓存）/
+ * 模块拆分（M4 + D2 合一）：实现体分布于 ajv-validator.ts（编译缓存）/
  * schema-guards.ts（形态守卫）/ execute.ts（校验编排）/ tool-definition.ts（工具定义）/
- * workflow-hook.ts（hook + RetryState）/ loop-gate.ts（D3 失败闸门）。
- * 本文件仅剩 entry 装配与 re-export。
+ * workflow-hook.ts（唯一装配入口 + steer 文案）/ loop-gate.ts（合一状态机 +
+ * 错误签名归一化 + terminal 副作用链）。本文件仅剩 entry 装配与 re-export。
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { setupLoopGate, LoopGate } from "./loop-gate.js";
+import { WorkflowGate } from "./loop-gate.js";
 import { executeStructuredOutput } from "./execute.js";
 import {
 	createDailyToolDefinition,
@@ -37,7 +31,7 @@ import {
 	ENV_SCHEMA,
 	SO_SCHEMA_SIZE_WARN_BYTES,
 } from "./tool-definition.js";
-import { RetryState, setupWorkflowHook } from "./workflow-hook.js";
+import { setupWorkflowHook } from "./workflow-hook.js";
 
 /** Pi Extension API — properly typed via ExtensionAPI from pi-coding-agent SDK */
 type PiAPI = ExtensionAPI;
@@ -49,9 +43,7 @@ export {
 	createWorkflowToolDefinition,
 	ENV_SCHEMA,
 	SO_SCHEMA_SIZE_WARN_BYTES,
-	RetryState,
-	setupLoopGate,
-	LoopGate,
+	WorkflowGate,
 };
 
 // ── Extension entry ────────────────────────────────────────────
@@ -60,13 +52,11 @@ export default function structuredOutputExtension(pi: PiAPI): void {
 	const schemaEnv = process.env[ENV_SCHEMA];
 
 	if (schemaEnv) {
-		// ── Workflow 模式：单参数工具（注册期 fail-fast 防御）+ 强制调用 hook + 失败闸门 ──
+		// ── Workflow 模式：单参数工具（注册期 fail-fast 防御）+ 双闸门合一 hook ──
+		// D2：软 steer 与硬杀由同一 WorkflowGate 状态机承载（单状态机单 listener），
+		// terminal 单字段单写，硬杀不需要向 steer 侧做任何回调同步。
 		pi.registerTool(createWorkflowToolDefinition(schemaEnv));
-		const hookState = setupWorkflowHook(pi, schemaEnv);
-		// D3/U2：闸门 terminal（同签名失败 ×3）→ 标记 hook 状态停 steer，写日志后
-		// ctx.shutdown() 优雅终止（RPC mode 于 agent_settled 后 exit）。硬闸门在软
-		// steer 之上兜底：G2 与模型配合度无关。
-		setupLoopGate(pi, { onTerminal: () => hookState.markTerminal() });
+		setupWorkflowHook(pi, schemaEnv);
 	} else {
 		// ── 日常模式：双参数自报形态（行为不变，G4）──
 		pi.registerTool(createDailyToolDefinition());

package/src/loop-gate.ts

@@ -1,5 +1,10 @@
 /**
- * 有界失败闸门（D3，U2 / M2）——G2「失败必有界」的执行体。
+ * 有界失败闸门 + steer 记账——双闸门合一状态机（D2 单状态机）+ G2「失败必有界」执行体。
+ *
+ * 状态归属（D2 单状态机）：软 steer（workflow-hook 的重试提醒）与硬杀（本文件的
+ * 同签名失败 terminal）共用 WorkflowGate 一份状态——terminal 单字段单写，turn_end
+ * 守卫链与硬杀幂等短路读同一份事实；若拆成两个状态机，terminal 双写就需要跨对象
+ * 回调同步，漏接线即 steer 与硬杀失步（单状态机使失步在结构上不可能）。
  *
  * 通道选型（设计 §6.3；pi 0.84.1 实装，登记 PS-20）：
  *   参数层失败（事故主形态）在 pi-ai validateToolArguments 抛错（validation.js:272-273）、
@@ -8,8 +13,9 @@
  *   的计数通道是 tool_execution_end 事件（sequential/parallel 两路径的 immediate
  *   分支均 emitToolExecutionEnd：agent-loop.js:277/:318/:348/:358）。
  *
- * 状态机：
- *   - 只统计 name=structured-output 的 isError 事件；其他工具的成功/失败均忽略。
+ * 硬杀侧转移（onToolExecEnd 的 gate 段）：
+ *   - 只统计 name=structured-output 的 isError 事件；其他工具的成功/失败均忽略
+ *     （toolName 过滤在装配层，见 workflow-hook.setupWorkflowHook）。
  *   - 错误签名归一化（审查项#7 签名哈希化）：截掉 "Received arguments:" 起的实参
  *     回显后，提取错误字段/路径 token 集合排序哈希为签名——集合不变 = 模型无进展
  *     （重复同一批字段错误），集合变化（含缩小 = 渐进修复）= 模型在推进。旧 500c
@@ -29,12 +35,21 @@
  *     写日志（stderr + appendEntry 双通道，含 §5.2 形态 b 恢复指引）后
  *     ctx.abort()（停当前 turn，截断 token 燃烧窗口）+ ctx.shutdown() 优雅终止
  *     子进程（RPC mode 在 agent_settled 后 exit），并武装 15s 兜底硬退 timer
- *    （R3 F-2 bounded teardown，覆盖 pi 挂死不 settle 的异常态）。
+ *    （R3 F-2 bounded teardown，覆盖 pi 挂死不 settle 的异常态；副作用序列见
+ *     runTerminalTeardown，装配层在 newlyTerminal 时调用）。
  *   - 成功调用清零（模型走通即无循环）。
  *
- * 与 workflow-hook 的关系：terminal 态经 onTerminal 回调标记 RetryState.terminal，
- * turn_end hook 据此不再 steer（防御性保留——shutdown 正常生效时进程已终止，
- * 该分支是 shutdown 失败路径下的保险）。
+ * steer 侧转移（onToolExecEnd 的记账段 + onTurnEnd，转移表锁定于 retry-state.test.ts）：
+ *   - 失败：soCallCount++ / lastSchemaError 记录（turn_end steer 的回灌文案原料）。
+ *   - 成功：soSucceededEver=true（终态，后续 turn_end 不再干预）。
+ *   - onTurnEnd 仅重置 steer 侧（soCallCount=0 / hookRetryCount++ / lastSchemaError=null），
+ *     **不触碰硬杀侧连续失败计数**——跨 turn 的同签名计数连续性是「3 轮各失败 1 次
+ *     仍会 terminal」的等价前提（characterization-hook ③ 锁定）。
+ *
+ * 与 workflow-hook 的关系：本文件导出状态机与 terminal 副作用链（runTerminalTeardown），
+ * 装配唯一入口在 workflow-hook.setupWorkflowHook（单状态机单 listener：每个事件至多
+ * 一个 listener，同一 tool_execution_end 内先 steer 记账后硬杀计数——与合一前两
+ * listener 的注册顺序一致）。
  *
  * 诚实边界（设计 §6.3）：闸门只终止「同签名无进展」这一种循环形态；签名不断
  * 变化的长尾低效不触发闸门，仍由 workflow 层 maxTurns 兜底。
@@ -43,21 +58,13 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { guardStaleCtx, isRecord, toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
-import { isToolExecutionEndEvent } from "./schema-guards.js";
-import {
-	extractToolErrorText,
-	SIGNATURE_MAX_CHARS,
-	truncateText,
-} from "./text-primitives.js";
+import { SIGNATURE_MAX_CHARS, truncateText } from "./text-primitives.js";
 
 type PiAPI = ExtensionAPI;
 
-// 依赖方向说明：本模块 → text-primitives（共享叶节点，导出复用勿复制）。原先经
-// workflow-hook 取 extractToolErrorText 构成的模块环已破除——双方互引的纯函数/常量
-// 下沉到 text-primitives，依赖图单向（loop-gate → text-primitives ← workflow-hook）。
-
-/** 与 tool-definition.ts 的 TOOL_NAME 对应。 */
-const TOOL_NAME = "structured-output";
+// 依赖方向说明：本模块 → text-primitives（共享叶节点，导出复用勿复制），依赖图单向
+//（workflow-hook → loop-gate → text-primitives；D2 后装配层 workflow-hook 消费本模块
+// 的状态机与 terminal 副作用链，本模块不反向依赖装配层）。
 
 /** 连续同签名失败阈值（设计 §6.3：对齐 qwen-code 的 3；workflow 子进程单用途短会话，更快失败更省）。 */
 export const MAX_CONSECUTIVE_FAILURES = 3;
@@ -337,26 +344,65 @@ export function normalizeErrorSignature(errorText: string): string {
 }
 
 /**
- * structured-output 失败循环闸门状态机（纯逻辑，可单测）。
+ * structured-output 双闸门合一状态机（D2 单状态机；纯逻辑，可单测）。
  *
- * 转移表（loop-gate.test.ts 锁定）：
- *   - onToolExecEnd(false)            → 计数/签名清零（成功短路）
- *   - onToolExecEnd(true, text)       → 签名同：计数++；签名异：计数=1（新一轮连续从此失败起算）
- *   - 计数达 MAX_CONSECUTIVE_FAILURES → terminal=true（不可逆；此后任何输入不再变化）
+ * 状态分区（一个对象、一份 terminal 事实）：
+ *   - steer 侧（workflow-hook turn_end 消费）：soCallCount / soSucceededEver /
+ *     hookRetryCount / lastSchemaError。
+ *   - 硬杀侧：lastSignature / consecutiveFailures / lastErrorText。
+ *   - 共享终态：terminal——硬杀触发后置位（不可逆，仅 reset() 可清），turn_end
+ *     守卫链据此停 steer，硬杀计数据此幂等短路。
+ *
+ * 转移表（loop-gate.test.ts / retry-state.test.ts 锁定）：
+ *   onToolExecEnd(hasError, errorText?)（每事件一次，先记账后计数——与合一前两
+ *   listener 的注册顺序一致）：
+ *   - steer 记账段（不受 terminal 短路影响：terminal 后迟到的失败仍记录，闸门自身
+ *     幂等，重复事件无害）：
+ *     - (!hasError)            → soCallCount++ / soSucceededEver=true
+ *     - (hasError, errorText)  → soCallCount++ / lastSchemaError=errorText ?? 通用提示
+ *   - 硬杀计数段（terminal 后幂等短路，任何输入不再变化）：
+ *     - onToolExecEnd(false)   → 计数/签名清零（成功短路）
+ *     - onToolExecEnd(true)    → 签名同：计数++；签名异：计数=1（新一轮连续从此失败起算）
+ *     - 计数达 MAX_CONSECUTIVE_FAILURES → terminal=true（返回 newlyTerminal=true，
+ *       装配层据此触发 runTerminalTeardown）
+ *   onTurnEnd()（仅当 turn_end 判定要 steer 且发送成功时由装配层调用）：
+ *     → soCallCount=0 / hookRetryCount++ / lastSchemaError=null；硬杀侧字段一律不动
+ *     （跨 turn 同签名计数连续性，见文件头注释 steer 侧转移段）。
  */
-export class LoopGate {
-	terminal = false;
+export class WorkflowGate {
+	// ── steer 侧 ──────────────────────────────────────────────
+	soCallCount = 0;
+	soSucceededEver = false;
+	hookRetryCount = 0;
+	lastSchemaError: string | null = null;
+	// ── 硬杀侧 ────────────────────────────────────────────────
 	private lastSignature: string | null = null;
 	consecutiveFailures = 0;
 	/** 最近一次失败的原始终态文本（截断后），供 terminal 日志引用。 */
 	lastErrorText: string | null = null;
+	// ── 共享终态（单字段单写：硬杀计数段置位，两闸门读同一份）──────
+	terminal = false;
 
-	/** 记录一次 structured-output tool 执行结果。hasError = event.isError === true。 */
+	/**
+	 * 记录一次 structured-output tool 执行结果。hasError = event.isError === true。
+	 * 返回硬杀侧形态（装配层只消费 newlyTerminal）；steer 决策不经返回值表达——
+	 * turn_end 时刻由 shouldSkipSteer 按状态字段推导（tool_execution_end 时刻无
+	 * 消费者，返回值携带只是死字段）。
+	 */
 	onToolExecEnd(hasError: boolean, errorText?: string): {
 		terminal: boolean;
 		/** 仅在「本次调用触发 terminal」时为 true（幂等：terminal 后恒 false）。 */
 		newlyTerminal: boolean;
 	} {
+		// steer 记账段（先于硬杀段：与合一前两 listener 的注册顺序一致；无 terminal 短路）
+		this.soCallCount++;
+		if (!hasError) {
+			this.soSucceededEver = true;
+		} else {
+			this.lastSchemaError = errorText ?? "structured-output call failed";
+		}
+
+		// 硬杀计数段（terminal 幂等短路在最前：置位后成功/失败都不再变化）
 		if (this.terminal) return { terminal: true, newlyTerminal: false };
 
 		if (!hasError) {
@@ -383,6 +429,28 @@ export class LoopGate {
 		return { terminal: false, newlyTerminal: false };
 	}
 
+	/**
+	 * turn 收尾（仅当要 steer 且发送成功时调用）：重置本 turn 计数、累计重试次数、
+	 * 清空错误。硬杀侧字段不动——成功路径之外的连续失败计数跨 turn 连续。
+	 */
+	onTurnEnd(): void {
+		this.soCallCount = 0;
+		this.hookRetryCount++;
+		this.lastSchemaError = null;
+	}
+
+	/** 全字段归零（当前无调用方；保留作状态机完整契约——含 D2 合一后的硬杀侧字段）。 */
+	reset(): void {
+		this.soCallCount = 0;
+		this.soSucceededEver = false;
+		this.hookRetryCount = 0;
+		this.lastSchemaError = null;
+		this.lastSignature = null;
+		this.consecutiveFailures = 0;
+		this.lastErrorText = null;
+		this.terminal = false;
+	}
+
 	/** 当前归一化签名（字段集合哈希或 fallback 前缀；无失败史时 null；测试与日志用）。 */
 	get signature(): string | null {
 		return this.lastSignature;
@@ -462,7 +530,7 @@ export function armForceExitTeardown(): void {
  *   - appendEntry：session JSONL 持久化记录（事后排查通道，不进 LLM 上下文）
  * 两者内容同源，指引文案逐字对齐设计 §5.2。
  */
-function writeTerminatedLog(pi: PiAPI, gate: LoopGate): void {
+function writeTerminatedLog(pi: PiAPI, gate: WorkflowGate): void {
 	const lastError = gate.lastErrorText ?? "(no error text)";
 	const stderrLines = [
 		`[structured-output gate] Terminated: the same validation error occurred ${MAX_CONSECUTIVE_FAILURES} times consecutively; shutting down this single-purpose workflow subprocess.`,
@@ -489,56 +557,36 @@ function writeTerminatedLog(pi: PiAPI, gate: LoopGate): void {
 	}
 }
 
-export interface LoopGateOptions {
-	/** terminal 触发时的回调（index.ts 用于标记 RetryState.terminal，hook 据此停 steer）。 */
-	onTerminal?: () => void;
-}
-
 /**
- * 注册 tool_execution_end 闸门监听（仅 workflow 模式装配，见 index.ts）。
+ * terminal 触发时的副作用链（装配层在 gate.onToolExecEnd 返回 newlyTerminal 时调用，
+ * 见 workflow-hook.setupWorkflowHook）。
  *
- * terminal 触发时序（R3 F-2 bounded teardown）：onTerminal 回调（同步，先标记
- * hook 状态）→ 写日志（stderr + appendEntry 双通道，R3 F-3）→ ctx.abort()（中止
- * 当前 agent 操作——截断「shutdown 请求后当前 turn 的 bash/read/流式继续跑、模型
- * 继续烧 token」的窗口，~25s 实测窗口在 abort 后即止）→ ctx.shutdown()（RPC mode
- * 置 shutdownRequested，agent_settled 后进程 exit(0)，父进程走「子进程结束但未
- * 产出 structured-output」的既有失败路径）→ armForceExitTeardown()（15s 兜底硬退，
- * 覆盖 pi 挂死不 settle 的异常态；方案依据见该函数注释）。
+ * 时序（R3 F-2 bounded teardown）：写日志（stderr + appendEntry 双通道，R3 F-3）→
+ * ctx.abort()（中止当前 agent 操作——截断「shutdown 请求后当前 turn 的 bash/read/
+ * 流式继续跑、模型继续烧 token」的窗口，~25s 实测窗口在 abort 后即止）→
+ * ctx.shutdown()（RPC mode 置 shutdownRequested，agent_settled 后进程 exit(0)，
+ * 父进程走「子进程结束但未产出 structured-output」的既有失败路径）→
+ * armForceExitTeardown()（15s 兜底硬退，覆盖 pi 挂死不 settle 的异常态；方案依据
+ * 见该函数注释）。
  */
-export function setupLoopGate(pi: PiAPI, options: LoopGateOptions = {}): LoopGate {
-	const gate = new LoopGate();
-
-	pi.on("tool_execution_end", async (event: unknown, ctx: ExtensionContext) => {
-		if (!isToolExecutionEndEvent(event)) return;
-		if (event.toolName !== TOOL_NAME) return;
-
-		const outcome = gate.onToolExecEnd(
-			event.isError === true,
-			extractToolErrorText(event.result),
-		);
-		if (!outcome.newlyTerminal) return;
-
-		options.onTerminal?.();
-		writeTerminatedLog(pi, gate);
-		// stale ctx 防御（crash-resilience D1）：abort/shutdown 均在 pi assertActive 面
-		// （PS-30，runner.js createContext）——session 替换窗口触发 terminal 时无人接的
-		// 同步 throw 会经 async handler 变 rejected Promise 杀 pi 进程。stale 静默跳过
-		// 优雅退出（此时进程的存在意义已随 session 替换消失），armForceExitTeardown 的
-		// 15s 硬退兜底保持武装——自清理语义不丢。非 stale 错误原样上抛（守卫不吞真实 bug）。
-		guardStaleCtx(() => {
-			ctx.abort();
-			ctx.shutdown();
-		}, {
-			label: "structured-output:terminal-teardown",
-			onStale: (error) => {
-				process.stderr.write(
-					`[structured-output gate] terminal teardown skipped (stale ctx, session replaced): `
-						+ `${toErrorMessage(error)}; force-exit timer stays armed.\n`,
-				);
-			},
-		});
-		armForceExitTeardown();
+export function runTerminalTeardown(pi: PiAPI, gate: WorkflowGate, ctx: ExtensionContext): void {
+	writeTerminatedLog(pi, gate);
+	// stale ctx 防御（crash-resilience D1）：abort/shutdown 均在 pi assertActive 面
+	// （PS-30，runner.js createContext）——session 替换窗口触发 terminal 时无人接的
+	// 同步 throw 会经 async handler 变 rejected Promise 杀 pi 进程。stale 静默跳过
+	// 优雅退出（此时进程的存在意义已随 session 替换消失），armForceExitTeardown 的
+	// 15s 硬退兜底保持武装——自清理语义不丢。非 stale 错误原样上抛（守卫不吞真实 bug）。
+	guardStaleCtx(() => {
+		ctx.abort();
+		ctx.shutdown();
+	}, {
+		label: "structured-output:terminal-teardown",
+		onStale: (error) => {
+			process.stderr.write(
+				`[structured-output gate] terminal teardown skipped (stale ctx, session replaced): `
+					+ `${toErrorMessage(error)}; force-exit timer stays armed.\n`,
+			);
+		},
 	});
-
-	return gate;
+	armForceExitTeardown();
 }

package/src/text-primitives.ts

@@ -11,7 +11,7 @@
 
 /**
  * 闸门签名侧截断上限：① normalizeErrorSignature fallback 分支（提取不到字段 token 的
- * 非校验类错误文本降级为裸前缀做等值比较，消费方 loop-gate）；② LoopGate.lastErrorText
+ * 非校验类错误文本降级为裸前缀做等值比较，消费方 loop-gate）；② WorkflowGate.lastErrorText
  * （terminal 日志引用，不进模型上下文，消费方 loop-gate）。与 steer 回灌错误块上限
  * （STEER_ERROR_MAX_CHARS）语义独立（F5 拆分：签名只做比较原料、可随实现演化；steer
  * 是模型可见文本预算），两上限不共享数值演化。

package/src/workflow-hook.ts

@@ -1,19 +1,28 @@
 /**
- * Workflow hook：turn_end 时检查模型是否成功调用 structured-output 工具。
- * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
- * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
+ * Workflow hook 装配：D2 单状态机单 listener 的唯一装配入口。
  *
- * RetryState：从旧 4 个 mutable 闭包（soCallCount/soSucceededEver/hookRetryCount/
- * lastSchemaError）显式化为类——per-turn reset 时机成为可单测的显式契约：
- * onTurnEnd() 仅在「判定要 steer」时调用（守卫链 toolUse/超上限/成功短路均不调）。
+ * 装配形态（workflow 模式，见 src/index.ts）：
+ *   - tool_execution_end：唯一 listener——喂 loop-gate 的 WorkflowGate（合一状态机：
+ *     steer 记账段 + 硬杀计数段，先记账后计数），newlyTerminal 时触发硬杀副作用链
+ *     （runTerminalTeardown：日志 → abort+shutdown → 15s 兜底硬退）。
+ *   - turn_end：唯一 listener——模型未成功产出 structured-output 时以 steer 方式注入
+ *     重试提醒（软闸门），提示词不伪装用户气泡，对话流用户内容 100% 来自用户输入；
+ *     最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
+ *
+ * 软硬闸门合一语义：terminal 是 WorkflowGate 上的单一事实——硬杀计数段置位后，
+ * turn_end 守卫链第 0 条据此停 steer；两闸门间无任何回调接线（terminal 若双写于
+ * 两个状态机，就必须跨对象回调同步，漏接线即 steer 与硬杀失步——单状态机单写使
+ * 失步在结构上不可能）。
+ *
+ * steer 文案/预算逻辑（buildSteerReminder / shouldSkipSteer / writeSteerFailedLog）
+ * 变化原因是提示词工程迭代，与硬杀计数（错误签名归一化）分文件维护。
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
-// 截断原语与错误块预算来自 text-primitives（共享叶节点，导出复用勿复制）。原
-// 「反向依赖（环）」已破除：本模块不再 import loop-gate，依赖图单向
-// （loop-gate → text-primitives ← workflow-hook）。
+import { WorkflowGate, runTerminalTeardown } from "./loop-gate.js";
+// 截断原语与错误块预算来自 text-primitives（共享叶节点，导出复用勿复制）。
 import {
 	extractToolErrorText,
 	STEER_ERROR_MAX_CHARS,
@@ -27,99 +36,25 @@ import { isObjectRootSchema } from "./execute.js";
 type PiAPI = ExtensionAPI;
 
 // 与 tool-definition.ts 的 TOOL_NAME 对应（本模块只监听该工具的 execution 事件；
-// 保持依赖图单向：workflow-hook → schema-guards，不 import tool-definition）。
+// 依赖图单向：workflow-hook → schema-guards / loop-gate / text-primitives，不成环）。
 const TOOL_NAME = "structured-output";
 const MAX_HOOK_RETRIES = 2;
 
-/**
- * structured-output 调用状态机（IF-7，export 契约——M5 从本模块 import）。
- *
- * 转移表（M4-TC-2 单测锁定）：
- *   - onToolExecEnd(false)      → soCallCount++ / soSucceededEver=true（成功短路终态）
- *   - onToolExecEnd(true, err)  → soCallCount++ / lastSchemaError=err ?? 通用提示
- *   - onTurnEnd()               → soCallCount=0 / hookRetryCount++ / lastSchemaError=null
- *     （仅当「判定要 steer 且发送成功」时调用——守卫链 toolUse/error/aborted/超上限/
- *      成功短路/发送失败均不调，故 toolUse 保留 soCallCount、超上限保留
- *      lastSchemaError，与旧 4-closure 逐点一致）
- *
- * terminal 态（D3/U2）：由 loop-gate 在同签名失败达 3 次时经 markTerminal() 置位，
- * turn_end hook 据此不再 steer——防御性保留：shutdown 正常生效时进程已终止，
- * 此分支是 shutdown 失败路径下的保险。terminal 不影响 onToolExecEnd 记录
- * （闸门自身幂等，重复事件无害）。
- */
-export class RetryState {
-	soCallCount = 0;
-	soSucceededEver = false;
-	hookRetryCount = 0;
-	lastSchemaError: string | null = null;
-	terminal = false;
-
-	/** 闸门 terminal 置位（loop-gate 经 index.ts 回调调用；不可逆，仅 reset() 可清）。 */
-	markTerminal(): void {
-		this.terminal = true;
-	}
-
-	/** 记录一次 structured-output tool 执行结果。hasError = event.isError === true。 */
-	onToolExecEnd(hasError: boolean, errorMsg?: string): { shouldSteer: boolean } {
-		this.soCallCount++;
-		if (!hasError) {
-			this.soSucceededEver = true;
-			return { shouldSteer: false };
-		}
-		this.lastSchemaError = errorMsg ?? "structured-output call failed";
-		return { shouldSteer: true };
-	}
-
-	/** turn 收尾（仅当要 steer 时调用）：重置本 turn 计数、累计重试次数、清空错误。 */
-	onTurnEnd(): void {
-		this.soCallCount = 0;
-		this.hookRetryCount++;
-		this.lastSchemaError = null;
-	}
-
-	/** 五字段归零（当前无调用方；保留作状态机完整契约——含 U2 新增 terminal 态）。 */
-	reset(): void {
-		this.soCallCount = 0;
-		this.soSucceededEver = false;
-		this.hookRetryCount = 0;
-		this.lastSchemaError = null;
-		this.terminal = false;
-	}
-}
-
 /** steer 发送失败告警的 appendEntry customType（session JSONL 持久化，不进 LLM 上下文）。 */
 export const HOOK_ENTRY_TYPE = "structured-output:hook";
 
 /**
- * steer 发送失败告警（审查项#8 失败路径）：双通道落盘（同 loop-gate writeTerminatedLog
- * 惯例）——stderr 直出 + appendEntry 持久化。预算未扣减由「不调 onTurnEnd」结构保证，
- * 下一个正常收尾的轮仍会重试 steer，不产生静默哑火。
+ * steer reminder 的 sendMessage customType（role:"custom" 消息，pi convertToLlm 对其
+ * 无条件转 LLM user 消息——LLM 可见性与 user message 无差别；display:false 不渲染
+ * 用户气泡，对话流归属语义结构性正确。锚点登记 docs/pi-semantics.json PS-43：
+ * pi dist/core/messages.js:89-96 case "custom" 无条件 role:"user"）。
  */
-function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): void {
-	const message = toErrorMessage(err);
-	process.stderr.write(
-		`[structured-output hook] steer send failed (retry budget NOT consumed, will retry at next turn end): ${message}\n`,
-	);
-	try {
-		pi.appendEntry(HOOK_ENTRY_TYPE, {
-			event: "steer_send_failed",
-			hookRetryCount,
-			error: message,
-			guidance:
-				"The steering message could not be delivered (e.g. compaction in progress or extension deactivated); the retry budget was preserved and the hook will retry at the next turn end.",
-		});
-	} catch (appendErr) {
-		// appendEntry 失败不阻断 hook——stderr 通道已落，此处补诊断（同 cache-probe 惯例）
-		process.stderr.write(
-			`[structured-output hook] appendEntry failed: ${toErrorMessage(appendErr)}\n`,
-		);
-	}
-}
+export const RETRY_REMINDER_CUSTOM_TYPE = "structured-output:retry-reminder";
 
 /**
  * steer 守卫链（原 turn_end handler 内联守卫提取，判定顺序与旧实现逐条一致）。
  * 命中任一守卫即跳过 steer，且调用方不调 onTurnEnd（toolUse/error/aborted 保留
- * soCallCount、超上限保留 lastSchemaError，与旧 4-closure 逐点一致）：
+ * soCallCount、超上限保留 lastSchemaError，与合一前逐点一致）：
  *   0. 闸门 terminal（D3/U2）：同签名失败已满 3 次、shutdown 已发——不再 steer，
  *      让进程终止（防御性保留：shutdown 正常生效时进程已死，到不了这里）
  *   1. 已经成功调用过 structured-output，不再干预
@@ -131,7 +66,7 @@ function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): v
  *      chatMode 复用子进程时会泄漏成下一轮的陈旧指令——不发送
  *   5. 超过重试上限：放弃，让子进程自然结束（调用方据 result.error 判定失败）
  */
-function shouldSkipSteer(state: RetryState, event: unknown): boolean {
+function shouldSkipSteer(state: WorkflowGate, event: unknown): boolean {
 	if (state.terminal) return true;
 	if (state.soSucceededEver) return true;
 	if (!isTurnEndEvent(event)) return true;
@@ -193,40 +128,68 @@ function buildSteerReminder(
 }
 
 /**
- * 注册 turn_end hook，检查模型是否成功调用 structured-output 工具。
- * 未成功时通过 pi.sendUserMessage({deliverAs:"steer"}) 注入 steering message 重试。
- * 最多重试 MAX_HOOK_RETRIES 次，防止无限循环。
- *
- * @returns 共享的 RetryState（U2：index.ts 拿它接线 loop-gate 的 onTerminal 回调）。
+ * steer 发送失败告警（审查项#8 失败路径）：双通道落盘（同 loop-gate writeTerminatedLog
+ * 惯例）——stderr 直出 + appendEntry 持久化。预算未扣减由「不调 onTurnEnd」结构保证，
+ * 下一个正常收尾的轮仍会重试 steer，不产生静默哑火。
+ */
+function writeSteerFailedLog(pi: PiAPI, hookRetryCount: number, err: unknown): void {
+	const message = toErrorMessage(err);
+	process.stderr.write(
+		`[structured-output hook] steer send failed (retry budget NOT consumed, will retry at next turn end): ${message}\n`,
+	);
+	try {
+		pi.appendEntry(HOOK_ENTRY_TYPE, {
+			event: "steer_send_failed",
+			hookRetryCount,
+			error: message,
+			guidance:
+				"The steering message could not be delivered (e.g. compaction in progress or extension deactivated); the retry budget was preserved and the hook will retry at the next turn end.",
+		});
+	} catch (appendErr) {
+		// appendEntry 失败不阻断 hook——stderr 通道已落，此处补诊断（同 cache-probe 惯例）
+		process.stderr.write(
+			`[structured-output hook] appendEntry failed: ${toErrorMessage(appendErr)}\n`,
+		);
+	}
+}
+
+/**
+ * 装配 workflow 模式的双闸门（D2 唯一装配入口，仅 workflow 模式调用，见 src/index.ts）。
  *
- * 两种失败形态都会触发 steer：
- * 1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
- * 2. 调了但全是 isError（soCallCount > 0 && !soSucceededEver）→ 注入具体校验错误
- *    + 正确 schema。旧实现在此处撒手交给 Pi 自然修正，但模型遇到 "Invalid JSON Schema"
- *    时无法自行修正（它不知道正确 schema 长什么样），实测会放弃 → 子进程正常退出 →
- *    workflow 把单点失败放大成整批崩溃。故此处主动 steer 并回灌错误细节。
+ * 每个事件至多一个 listener（单 listener 契约，D2）：
+ *   - tool_execution_end：结构守卫 → toolName 过滤 → WorkflowGate.onToolExecEnd
+ *     （合一状态机：先 steer 记账后硬杀计数）→ newlyTerminal 时 runTerminalTeardown
+ *     （terminal 时序与副作用明细见该函数注释）。
+ *   - turn_end：守卫链 shouldSkipSteer → 两种失败形态都 steer：
+ *     1. 完全没调用（soCallCount === 0）→ 注入"必须调用"提示 + 正确 schema
+ *     2. 调了但全是 isError（soCallCount > 0 && !soSucceededEver）→ 注入具体校验错误
+ *        + 正确 schema。旧实现在此处撒手交给 Pi 自然修正，但模型遇到 "Invalid JSON Schema"
+ *        时无法自行修正（它不知道正确 schema 长什么样），实测会放弃 → 子进程正常退出 →
+ *        workflow 把单点失败放大成整批崩溃。故此处主动 steer 并回灌错误细节。
  *
  * 检测时序：Pi 保证同 turn 内所有 tool_execution_end 都在 turn_end 之前触发，
  * 故 turn_end 读取的状态已反映本 turn 全部 tool 调用结果。
  */
-export function setupWorkflowHook(pi: PiAPI, schemaJson: string): RetryState {
-	const state = new RetryState();
+export function setupWorkflowHook(pi: PiAPI, schemaJson: string): void {
+	const state = new WorkflowGate();
 
 	// 根类型判定与 {value} 包装判定同源（isObjectRootSchema，P6）：注册期
 	// createWorkflowToolDefinition 已对同一 schema 完成 assertJsonSchemaRoot fail-fast，
 	// 此处解析失败不可能到达；真失败时判定为非 object 根 → 包装契约文案（保守方向）。
 	const isObjectRoot = isObjectRootSchema(tryParseJson(schemaJson));
 
-	// 追踪 structured-output 调用结果：
-	// 成功 → soSucceededEver=true（终态，后续不再干预）
-	// 失败 → soCallCount++，记录 lastSchemaError，由 turn_end 决定是否 steer 重试
-	pi.on("tool_execution_end", async (event: unknown) => {
+	pi.on("tool_execution_end", async (event: unknown, ctx: ExtensionContext) => {
 		if (!isToolExecutionEndEvent(event)) return;
 		if (event.toolName !== TOOL_NAME) return;
-		state.onToolExecEnd(
+
+		// errorText 不在此处 fallback——合一状态机记账段/计数段对 undefined 同用
+		// "structured-output call failed" 通用提示（与合一前两 listener 传入形态等价）。
+		const outcome = state.onToolExecEnd(
 			event.isError === true,
-			extractToolErrorText(event.result) ?? "structured-output call failed",
+			extractToolErrorText(event.result),
 		);
+		if (!outcome.newlyTerminal) return;
+		runTerminalTeardown(pi, state, ctx);
 	});
 
 	pi.on("turn_end", async (event: unknown) => {
@@ -240,14 +203,18 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): RetryState {
 		// 故 onTurnEnd()（清空 lastSchemaError）必须在发送成功之后调用。
 		const reminder = buildSteerReminder(calledButFailed, state.lastSchemaError, schemaJson, isObjectRoot);
 
-		// 审查项#8：await 发送结果——发送失败（如 compaction 中 prompt() 抛错 / 扩展已
+		// 审查项#8：await 发送结果——发送失败（如 compaction 中开轮抛错 / 扩展已
 		// 被 assertActive 拒绝）不扣减重试预算（不调 onTurnEnd），否则 fire-and-forget
 		// 丢一份 steer + 白扣一次预算，两次即永久哑火。
-		// pi 0.84.1 实装（loader.js）：extension 侧 sendUserMessage 同步转发且吞掉异步
-		// rejection（转 emitError）返回 void——await 对 undefined 立即解析；此处的
-		// try/catch 兜住同步 throw（assertActive）与未来 pi 返回真 Promise 的形态。
+		// pi 0.84.4 实装（loader.js）：extension 侧 sendMessage 同步转发且吞掉异步
+		// rejection（bindCore .catch(emitError) 转事件）返回 void——await 对 undefined
+		// 立即解析；此处的 try/catch 兜住同步 throw（assertActive）与未来 pi 返回真
+		// Promise 的形态。
 		try {
-			await pi.sendUserMessage(reminder, { deliverAs: "steer" });
+			await pi.sendMessage(
+				{ customType: RETRY_REMINDER_CUSTOM_TYPE, content: reminder, display: false },
+				{ deliverAs: "steer", triggerTurn: true },
+			);
 		} catch (err) {
 			writeSteerFailedLog(pi, state.hookRetryCount, err);
 			return;
@@ -255,7 +222,4 @@ export function setupWorkflowHook(pi: PiAPI, schemaJson: string): RetryState {
 		// 发送成功才按本 turn 重置计数、累计重试次数、清空 lastSchemaError
 		state.onTurnEnd();
 	});
-
-	// U2：暴露共享状态——index.ts 接线 loop-gate 的 onTerminal 回调（markTerminal）
-	return state;
 }