@sema-agent/server 7.149.0 → 7.151.0

package/dist/orchestration/workflow-park-holder.js

@@ -0,0 +1,98 @@
+import { boundedRotation } from "../bounded-rotation.js";
+import { recordFailOpen } from "../observability/fail-open.js";
+import { deliverableEntryOf, holderPullDisposition, redeemHere, runChannelEnded } from "../parked-decide.js";
+import { heldParksOf, readRunParks } from "./workflow-agent-session-index.js";
+export class HeldParksHere {
+    ended;
+    runs = new Map();
+    constructor(ended = runChannelEnded) {
+        this.ended = ended;
+    }
+    noteLanded(runId, run) {
+        const parks = readRunParks(run);
+        if (parks === undefined)
+            return;
+        const tokens = heldParksOf(runId, parks).map((p) => p.token);
+        if (this.runs.has(runId)) {
+            this.runs.set(runId, { runId, scope: run.scope, tokens });
+            return;
+        }
+        if (tokens.length === 0)
+            return;
+        const entry = { runId, scope: run.scope, tokens };
+        this.runs.set(runId, entry);
+        const drop = () => void this.runs.delete(runId);
+        void this.ended(runId, run.scope).then(drop, (err) => {
+            recordFailOpen("server.workflow-park-holder.read-failed", `step=channel runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+            drop();
+        });
+    }
+    candidates() {
+        return [...this.runs.values()];
+    }
+}
+export const HOLDER_PULL_MAX_PER_TICK = 64;
+export const HOLDER_PULL_BUDGET_MS = 5_000;
+export const HOLDER_PULL_READ_TIMEOUT_MS = 2_000;
+function within(p, ms, what) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`${what} did not answer within ${ms}ms`)), ms);
+        timer.unref?.();
+    });
+    p.catch(() => undefined);
+    return Promise.race([p, timeout]).finally(() => clearTimeout(timer));
+}
+export function createWorkflowParkHolderPull(deps) {
+    const cursor = { offset: 0 };
+    const sources = { checkpointStore: deps.checkpointStore, workflowAgentSessionIndex: deps.workflowAgentSessionIndex, workflowRunStore: deps.workflowRunStore };
+    return async () => {
+        const items = deps.held.candidates().flatMap((r) => r.tokens.map((token) => ({ runId: r.runId, scope: r.scope, token })));
+        let delivered = 0;
+        let nextBeat = 0;
+        let left = 0;
+        const { visited, backlog, truncated } = await boundedRotation([{ items, cursor }], { maxPerTick: HOLDER_PULL_MAX_PER_TICK, budgetMs: HOLDER_PULL_BUDGET_MS }, async ({ runId, scope, token }) => {
+            let row;
+            try {
+                row = await within(deps.decisions.get(token), HOLDER_PULL_READ_TIMEOUT_MS, "workflow park decision read");
+            }
+            catch (err) {
+                recordFailOpen("server.workflow-park-holder.read-failed", `step=decision runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (row === null)
+                return;
+            let deliverable;
+            try {
+                deliverable = await within(deliverableEntryOf(sources, row), HOLDER_PULL_READ_TIMEOUT_MS, "workflow park card read");
+            }
+            catch (err) {
+                recordFailOpen("server.workflow-park-holder.read-failed", `step=card runId=${runId} err=${err instanceof Error ? err.message : String(err)}`);
+                return;
+            }
+            if (deliverable.kind !== "deliverable" || deliverable.entry.runId !== runId)
+                return;
+            const disposition = holderPullDisposition(await redeemHere(runId, scope, { token, outcome: row.outcome }), runId);
+            switch (disposition) {
+                case "delivered":
+                    delivered++;
+                    return;
+                case "next_beat":
+                    nextBeat++;
+                    return;
+                case "left":
+                    left++;
+                    return;
+                default: {
+                    const unhandled = disposition;
+                    throw new Error(`unhandled holder pull disposition: ${String(unhandled)}`);
+                }
+            }
+        }, deps.now);
+        if (truncated) {
+            deps.warn?.("workflow_park_holder_pull_truncated", { polled: visited, delivered, backlog, maxPerTick: HOLDER_PULL_MAX_PER_TICK, budgetMs: HOLDER_PULL_BUDGET_MS, resumeFromOffset: cursor.offset });
+        }
+        return { polled: visited, delivered, nextBeat, left, backlog, truncated };
+    };
+}
+//# sourceMappingURL=workflow-park-holder.js.map

package/dist/orchestration/workflow-record-fence.d.ts

@@ -0,0 +1,36 @@
+/**
+ * **workflow 记录的进程内记录栅栏**(local 后端:File / InMemory 记录店;SQL 孪生是 `SqlWorkflowRunStore.whileRunning` 的行锁事务)。
+ *
+ * ## 为什么在基店外包一层
+ * 持有一张停驻卡的 run 仍读作 `running` 时,决定行落在「这条 run 的记录仍在跑、仍持有这张卡」的原子段里(律的属主 = `workflow-park-decision.ts` 文件头)。
+ * 这一段要与这条 run 的**每一笔**记录写串行 —— 否则「判出在跑 → 落行」之间插进引擎的终态写,run 收场送达读不到这一行,决定被丢在已收场的 run 上。
+ * 本服务的记录写者有两个:引擎(经 journaling 装饰器 `JournalingWorkflowRunStore`)与 notify 门的收养翻转(`WorkflowNotifyGate.recover` 经基店翻 `running → failed`);
+ * core File 店的锁是它私有的。⇒ 互斥不能只放在 journaling 装饰器上:放在**基店外的这一只装饰器**里,两只写者都经它写,它就是本进程全部记录写者的同一只互斥。
+ *
+ * ## 律
+ * 按 runId 互斥:`put` / `update` / {@link FencedWorkflowRecordStore.whileRunning} 对同一条 run 一个接一个(先到先走);读(`get` / `listByScope`)与收割(只删终态行)
+ * 不进互斥(本装饰器不出按会话删那一口:与它所在的 journaling 装饰器同一个答案)。`whileRunning` 的 `fn` 是同步的(型上不许把写挪到段外),段里不许再经本店写同一条 run(会自锁)。
+ * 互斥只排同一进程里的写;SQL 后端的跨副本串行由行锁担(那里没有本装饰器)。
+ */
+import type { WorkflowRun, WorkflowRunStore } from "@sema-agent/core";
+import type { InProcessRecordFence, RecordFenced } from "./workflow-park-decision.js";
+export declare class FencedWorkflowRecordStore implements WorkflowRunStore, InProcessRecordFence {
+    private readonly inner;
+    /** runId → 这条 run 上最后一段的落定(链尾);链空了就摘掉(有界 = 此刻有段在排的 run 数)。 */
+    private readonly tails;
+    constructor(inner: WorkflowRunStore);
+    /** 同一条 run 上的段一个接一个:等前一段落定(成败都算落定)再走本段。 */
+    private serial;
+    put(id: string, run: WorkflowRun): Promise<void>;
+    update(id: string, scope: string, run: WorkflowRun, expect?: {
+        rev: number;
+    }): Promise<boolean>;
+    whileRunning<T>(runId: string, fn: (run: WorkflowRun) => T): Promise<RecordFenced<T>>;
+    get(id: string): Promise<WorkflowRun | null>;
+    listByScope(...args: Parameters<WorkflowRunStore["listByScope"]>): ReturnType<WorkflowRunStore["listByScope"]>;
+    reap(scope: string, now: number, opts?: {
+        maxAgeMs?: number;
+        keep?: number;
+    }): Promise<number>;
+}
+//# sourceMappingURL=workflow-record-fence.d.ts.map

package/dist/orchestration/workflow-record-fence.js

@@ -0,0 +1,42 @@
+export class FencedWorkflowRecordStore {
+    inner;
+    tails = new Map();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    serial(runId, segment) {
+        const before = this.tails.get(runId) ?? Promise.resolve();
+        const result = before.then(segment);
+        const tail = result.then(() => undefined, () => undefined);
+        this.tails.set(runId, tail);
+        void tail.then(() => {
+            if (this.tails.get(runId) === tail)
+                this.tails.delete(runId);
+        });
+        return result;
+    }
+    put(id, run) {
+        return this.serial(id, () => this.inner.put(id, run));
+    }
+    update(id, scope, run, expect) {
+        return this.serial(id, () => this.inner.update(id, scope, run, expect));
+    }
+    whileRunning(runId, fn) {
+        return this.serial(runId, async () => {
+            const run = await this.inner.get(runId);
+            if (run === null || run.status !== "running")
+                return { running: false };
+            return { running: true, value: fn(run) };
+        });
+    }
+    get(id) {
+        return this.inner.get(id);
+    }
+    listByScope(...args) {
+        return this.inner.listByScope(...args);
+    }
+    reap(scope, now, opts) {
+        return this.inner.reap(scope, now, opts);
+    }
+}
+//# sourceMappingURL=workflow-record-fence.js.map

package/dist/owner-faces.d.ts

@@ -52,7 +52,7 @@ export interface Caller {
     readonly principalRequired: boolean;
     readonly multiTenant: boolean;
 }
-/** 单机形下 core 写侧 `spec.principal ?? "default"` 铸出的租户键(壳随请求带的那一个):`j4` 一格的调用方条件。它是单机形的真租户键,不是哨兵。 */
+/** 单机形下 core 写侧给匿名任务落的那一格租户键(壳随请求带的那一个;换算 = `engine-identity.ts` 的 `engineScopeOf`):`j4` 一格的调用方条件。它是单机形的真租户键,不是哨兵。 */
 export declare const LEGACY_UNOWNED_AMNESTY_TENANT = "default";
 /**
  * 🔴 **调用方与行属主之间唯一的桥**:两个品牌在类型上不可比(`Subject === DurableOwnerKey` 编译红),只在这里按字节比。调用方一侧是**主体**(分区键):
@@ -112,9 +112,10 @@ export type FaceDoor = "P401" | "I401" | "I401r" | "none";
  *  · `deleted_false` —— 200 `{deleted:false}`(删除口幂等形:没删到东西);
  *  · `run_exists` —— 409 `conflict.run_exists`(提交重放:这把键 / 这只 taskId 已被占用);
  *  · `attach_absent` —— 404 `resume.session_not_found`「requireExistingSession: session does not exist …」(提交挂接:认领面没有「没有就建」可镜像,占用 = 不存在那一体);
+ *  · `workflow_missing` —— 404 `not_found.workflow` "workflow not found"(工作流按 id 四口;没有 / 看不见 / 会话断言不符同体);
  *  · `omit` —— 本模块不下发:调用点把「看不见」当「没有」走它自己的缺席路径(协议口的 RpcError / leader 404 / 嵌套可选字段省略)。
  */
-export type FaceProjection = "run_missing" | "task_missing" | "decision_missing" | "session_missing" | "exemption_missing" | "deleted_false" | "run_exists" | "attach_absent" | "omit";
+export type FaceProjection = "run_missing" | "task_missing" | "decision_missing" | "session_missing" | "exemption_missing" | "deleted_false" | "workflow_missing" | "run_exists" | "attach_absent" | "omit";
 /** 属主读不出(会话店交出具名拒「属主读不出」)时本口怎么读:`fold` = 读作没有这一行(同一只投影,原故障进运维日志一行);`raise` = 原故障照常上抛。 */
 export type FaceUnreadable = "fold" | "raise";
 /**
@@ -126,8 +127,8 @@ export type FaceUnreadable = "fold" | "raise";
  */
 export type FacePlacementUnreadable = "raise" | "ordinary";
 export interface Face {
-    /** 行的种类:run / 会话行(路由经 `http/owner-access.ts` 的门判)、停驻行 scope 列(`scope`)、ask 行 / 活登记 / 活问(`ask`)、收件条目(`inbox`)、列表面(`list`)。 */
-    readonly resource: "run" | "session" | "scope" | "ask" | "inbox" | "list";
+    /** 行的种类:run / 会话行(路由经 `http/owner-access.ts` 的门判)、工作流行(`workflow`:属主 = 引擎写下的 `scope` 列)、停驻行 scope 列(`scope`)、ask 行 / 活登记 / 活问(`ask`)、收件条目(`inbox`)、列表面(`list`)。 */
+    readonly resource: "run" | "session" | "workflow" | "scope" | "ask" | "inbox" | "list";
     /** 行资格里本口放哪几格。 */
     readonly grants: readonly RowQual[];
     /** fleet 资格里本口放哪几格(D1 列,见模块头注)。 */
@@ -385,6 +386,26 @@ export declare const FACES: {
         readonly unreadable: "raise";
         readonly placementUnreadable: "ordinary";
     };
+    readonly "workflow.read": {
+        readonly resource: "workflow";
+        readonly grants: readonly ["owner"];
+        readonly fleet: readonly [];
+        readonly operator: false;
+        readonly door: "P401";
+        readonly projection: "workflow_missing";
+        readonly unreadable: "raise";
+        readonly placementUnreadable: "raise";
+    };
+    readonly "workflow.steer": {
+        readonly resource: "workflow";
+        readonly grants: readonly ["owner"];
+        readonly fleet: readonly [];
+        readonly operator: false;
+        readonly door: "P401";
+        readonly projection: "workflow_missing";
+        readonly unreadable: "raise";
+        readonly placementUnreadable: "raise";
+    };
     readonly "scope.decide": {
         readonly resource: "scope";
         readonly grants: readonly ["owner", "open"];
@@ -456,6 +477,9 @@ export type SessionFaceId = {
 export type ListFaceId = {
     [F in FaceId]: (typeof FACES)[F]["resource"] extends "list" ? F : never;
 }[FaceId];
+export type WorkflowFaceId = {
+    [F in FaceId]: (typeof FACES)[F]["resource"] extends "workflow" ? F : never;
+}[FaceId];
 /**
  * **只看「验过的主体 + 运维位」的面**(派生型:行资格 ⊆ {owner, open} ∧ fleet 列空):这几只面的可见性与部署形、fleet 事实都无关 ——
  * 面表里给其中一行加上 `j4` / 任一 fleet 格,它就掉出本型,{@link keyAdmits} 的调用点编译红(那时它要一只完整的 {@link Caller})。

package/dist/owner-faces.js

@@ -74,6 +74,8 @@ export const FACES = {
     "session.policy": { resource: "session", grants: ["owner", "open", "anon_tree"], fleet: ["dev_open"], operator: true, door: "I401r", projection: "session_missing", unreadable: "raise", placementUnreadable: "ordinary" },
     "session.notify": { resource: "session", grants: ["owner", "open", "anon_tree"], fleet: ["dev_open"], operator: true, door: "P401", projection: "session_missing", unreadable: "raise", placementUnreadable: "raise" },
     "session.attach": { resource: "session", grants: ["owner", "open"], fleet: [], operator: false, door: "none", projection: "attach_absent", unreadable: "raise", placementUnreadable: "ordinary" },
+    "workflow.read": { resource: "workflow", grants: ["owner"], fleet: [], operator: false, door: "P401", projection: "workflow_missing", unreadable: "raise", placementUnreadable: "raise" },
+    "workflow.steer": { resource: "workflow", grants: ["owner"], fleet: [], operator: false, door: "P401", projection: "workflow_missing", unreadable: "raise", placementUnreadable: "raise" },
     "scope.decide": { resource: "scope", grants: ["owner", "open"], fleet: [], operator: true, door: "none", projection: "omit", unreadable: "raise", placementUnreadable: "raise" },
     "ask.decide": { resource: "ask", grants: ["owner", "open"], fleet: [], operator: true, door: "none", projection: "omit", unreadable: "raise", placementUnreadable: "raise" },
     "ask.answer": { resource: "ask", grants: ["owner", "open"], fleet: [], operator: false, door: "none", projection: "omit", unreadable: "raise", placementUnreadable: "raise" },

package/dist/parked-decide.d.ts

@@ -15,7 +15,7 @@ import { type BackgroundAgentRecord, type BackgroundAgentStore, type CheckpointS
 import type { ParkedReviveSurfaceFactory } from "./parked-revive-surface.js";
 import type { RebuiltInheritedGate } from "./boot/parked-revive-gate.js";
 import { type WorkflowRunParkKey, type WorkflowAgentSessionIndex } from "./orchestration/workflow-agent-session-index.js";
-import type { WorkflowParkDecisionStore, WorkflowParkOutcome } from "./orchestration/workflow-park-decision.js";
+import type { HolderFenceVerdict, WorkflowParkDecision, WorkflowParkDecisionStore, WorkflowParkOutcome } from "./orchestration/workflow-park-decision.js";
 import { type ApprovalLegOrigin } from "./approval-leg-origin.js";
 import type { SessionFace } from "./session-incarnation.js";
 import { type CardSettlePort } from "./card-settle-stored-scope.js";
@@ -127,16 +127,43 @@ type ParkedResumeEntry = NonNullable<RunInternals["workflowParkedResume"]>[numbe
  * 产物原样摊进那一跑的 `RunInternals`(部署方铸的 TRUSTED internals:不是 `TaskSpec` 字段、不是工具参数 —— 模型永远不能自己决定一次审批)。
  *
  * 产物 = 调用方自己带的那一份(`carried`:`/decide` 的投递跑带着它刚受理、行还没落的那条决定)∪ 这个会话的决定行(律与寿命的属主 =
- * `orchestration/workflow-park-decision.ts` 文件头),同一张卡以 `carried` 为准(它是要取代行上旧决定的那一个)。行这一侧逐条:
- *  · 子代卡此刻**仍 pending** 才供:读回 `null` / 状态不是 `pending` ⇒ 不供(引擎对「记着停驻、卡却已不 pending」的序数,有条目 ⇒ 当确认
- *    结算、没条目 ⇒ 拒续跑 —— 供一条过期条目会把后者改成前者);读卡抛 ⇒ 不供并计 `server.workflow-park-decision.card-unreadable`
- *    (这一读失败不代表引擎随后的那一读也失败;不供的方向是这一跑不带它、行留着给下一跑 —— 绝不把它变成一次确认);
- *  · 投递目标 = 这张卡**当下**的持有者 run(`findParkOrigin`,与 `/decide` 路由同一只判官):持有者判不出唯一一条(分叉 / 证不了 / 卡
- *    已在新 token 下再停)⇒ 不供(引擎只把条目交给 `resumeFromRunId` 恰是持有者的续跑;没有唯一持有者就没有可交付的那一跑)。
+ * `orchestration/workflow-park-decision.ts` 文件头),同一张卡以 `carried` 为准(它是要取代行上旧决定的那一个)。行这一侧逐条经
+ * {@link deliverableEntryOf}(子代卡仍 pending ∧ 当下持有者;引擎只把条目交给 `resumeFromRunId` 恰是持有者的续跑)。
  * 决定店读抛(local 账本闸合上 / SQL 一行坏体)⇒ 与读卡失败同律:这一店当「没有可供的行」,只交回 `carried`,计 `server.workflow-park-decision.store-unreadable`
  * (不跳过坏行照供其余:读不出的那一行可能正是取代了旧决定的那一笔;不拒起跑:不供是安全方向,卡仍 pending、可再决)。决定的写口照旧由店闸住。
  */
 export declare function heldWorkflowParkDecisions(sources: HeldWorkflowParkDecisionSources, hostSessionId: string, carried?: readonly ParkedResumeEntry[]): Promise<Pick<RunInternals, "workflowParkedResume">>;
+/**
+ * 一条决定行此刻的可交付性(闭集):
+ *  · `deliverable`     —— 交给引擎的那一条 + 它的当下持有者 + 子代那张卡此刻的存储行(仍 pending;属主 scope 与子会话 —— 收场送达按它判内部授权);
+ *  · `not_deliverable` —— 卡已不 pending / 读回 `null` / 判不出唯一的当下持有者(分叉 / 证不了 / 卡已在新 token 下再停);
+ *  · `unreadable`      —— 卡或持有者此刻读不出(店抛)。三个读者各按自己的语义处置:起跑读者 = 这一跑不带它;拉取腿 = 下一拍;收场送达 = 重投。
+ */
+export type DeliverableParkDecision = {
+    readonly kind: "deliverable";
+    readonly entry: ParkedResumeEntry;
+    readonly origin: Extract<ParkOrigin, {
+        kind: "workflow";
+    }>;
+    readonly card: {
+        readonly scope: string;
+        readonly sessionId: string;
+    };
+} | {
+    readonly kind: "not_deliverable";
+} | {
+    readonly kind: "unreadable";
+};
+/**
+ * 🔴 **一条决定行此刻可不可交付、交给谁 —— 逐行判的唯一一只**(交付行的三方同读:起跑读者 {@link heldWorkflowParkDecisions}、持有进程的拉取腿、run 收场送达):
+ *  · 子代卡此刻**仍 pending** 才交付:读回 `null` / 状态不是 `pending` ⇒ 不交付(引擎对「记着停驻、卡却已不 pending」的序数,有条目 ⇒ 当确认结算、没条目 ⇒ 拒续跑 ——
+ *    交一条过期条目会把后者改成前者);
+ *  · 投递目标 = 这张卡**当下**的持有者 run(与 `/decide` 路由同一只判官 `routeWorkflowPark`):判不出唯一一条 ⇒ 不交付;
+ *  · 卡或持有者读不出 ⇒ `unreadable`,计 `server.workflow-park-decision.card-unreadable`(这一读失败不代表引擎随后那一读也失败;不交付的方向是这一次不带它、行留着 ——
+ *    绝不把它变成一次确认)。
+ * 不读行上的承运者(`deliveredTaskId`):承运者是谁与「此刻交给谁」无关。
+ */
+export declare function deliverableEntryOf(sources: Required<Pick<HeldWorkflowParkDecisionSources, "checkpointStore" | "workflowAgentSessionIndex" | "workflowRunStore">>, row: WorkflowParkDecision): Promise<DeliverableParkDecision>;
 /**
  * pending checkpoint → parked bg 行匹配。
  *
@@ -309,10 +336,10 @@ export declare function buildParkedResumeOutcome(req: ParkedDecideRequest): Work
 /**
  * [ref] 车CM —— **第三条车道的计划**(纯函数;驱动本身归 resume 家族的那条腿,见下方「为什么不自建驱动」)。
  *
- * 🔴 **这份计划先交给持有这张卡的那条活 run**({@link deliverToHoldingRun}):run 仍在本进程里跑 ⇒ 决定由引擎在原 run 里用上,
- * 下面的续跑车道一步都不走;只有那条 run 已不能收决定(本进程里没有它在跑 / 它已挂起收场)时,计划才按下文落到续跑车道。
- * 判决 / 宿主两只拒臂在交给活 run 之前判:`remember` 拒的理由两条去路同真(两者的 200 都证不出引擎已提交);
- * 本服务只经会话的 Workflow 工具起 workflow,活在本进程里的 run 恒有发起会话 ⇒ 宿主拒臂只拦得住续跑车道上那种 run。
+ * 🔴 **持有这张卡的 run 仍读作 `running` ⇒ 这份计划先进记录栅栏**(唯一仲裁点;`orchestration/workflow-park-decision.ts` 文件头的律):决定行落在那条 run 的
+ * 记录行锁里,交给引擎由跑那条 run 的进程做({@link answerOfHolderRedeem} / 持有进程的拉取腿 / run 收场送达),下面的续跑车道一步都不走;
+ * 只有记录已不读作 `running` 时,计划才按下文落到续跑车道。判决 / 宿主两只拒臂在进栅栏之前判:`remember` 拒的理由两条去路同真(两者的 200 都证不出引擎已提交);
+ * 本服务只经会话的 Workflow 工具起 workflow,读作 `running` 的 run 恒有发起会话 ⇒ 宿主拒臂只拦得住续跑车道上那种 run。
  *
  * ## 这条车道为什么长这样(亲读 core 实现后的结论,不是从类型面推的)
  * 任务书原案是「server 直接 `startWorkflow({resumeFromRunId, parkedResume})`」。亲读安装的 core
@@ -390,57 +417,81 @@ export declare function planWorkflowParkedDecide(origin: Extract<ParkOrigin, {
     kind: "workflow";
 }>, req: ParkedDecideRequest): WorkflowParkedDecidePlan;
 /**
- * **持有这张卡的那条 run 还在本进程里跑吗 —— 在跑就把决定交给它**(workflow 停驻卡的唯一一种去法的前半;后半是续跑车道)。
+ * 续跑车道交给宿主模型的**指路**(`/decide` 的计划与 run 收场送达同一只;两条交付续跑车道的路读同一份文本)。
+ * 消息是给宿主模型的**指路**,不是能力:决定本身走 internals 的可信通道(模型永远不能自己决定审批)。
  *
- * ## 律(一条)
- * 一张 workflow 子代停驻卡的决定先交给持有它的那条 run:引擎根导出 `redeemWorkflowParks(runId, run.scope, [条目])` 是「这张停驻怎么处置」的唯一读法
- * (它查本进程的活 run 表;别的进程里的 run 它答 `not_active`)。引擎答 run 已不能收(`not_active`;`suspending` 且它的 `ended` 已落定)⇒
- * 交回 `resume_lane`,调用方照计划走续跑车道;其余每一个答词都在这里落成这次决断的应答,续跑车道一步不走 ——
- * 同一张卡在同一时刻只有一条去路(活 run 上把决定交给模型去调 `Workflow({resumeFromRunId})` 那一读法退役:引擎的 fork 守卫拒它)。
+ * 🔴 **本服务唯一的 `trusted: true` 铸点**。文本框架只看文本出自谁,不看按下按钮的是谁:这段话是**服务自己铸的**
+ * (下面三个结构位,没有一个字来自调用方),所以以系统源投递 —— 不论决定者是不是运维(wake 腿 `resumeWake` 原样转交,
+ * 不再从决定者身份推)。调用方的话(HTTP steer / `/wake` 的正文、hook 输出)恒 `trusted: false`;
+ * 结构钉 `test/steer-text-framing.test.ts` 普查全仓只此一处。
  *
- * ## 条目
- * 决定恒带结局(`{ token, outcome }`)。**带续跑重述键时送引擎的确认动词**(`{ token }`:确认从不授权驱动,卡仍 pending 时引擎答 `kept_parked`、
- * 停驻原样留下)—— 重述键只盖得到续跑车道的重建输入,活 run 上的子代带着它停驻时的表继续,所以活 run 在 ⇒ 400 拒(与后台子代同一个码);
- * run 不在 ⇒ 续跑车道照带重述键。「活不活」只问引擎这一处,不读第二只判官。确认不是无副作用的探针:卡恰在此刻已不待决 ⇒ 引擎把那一调结算成失败(`settled`,
- * 与任何决定撞上同一形同一个结局)⇒ 答 409 `decide.gate_moved`。
+ * 🔴 **只含结构位**(7.69.0 合并重扫 c1,安全轴)。core 对 `trusted:true` 的 steer 走 `formatHookFeedback` ⇒ 铸成**带 mark 的**
+ * `<system-reminder>`,而那个 mark 正是 core 教模型「带 mark 的才是引擎权威」的防冒名位。所以进这条
+ * 文本的每一个字都必须是 server/引擎自己能负责的事实:`runId`(引擎铸的 `w*`)、`callKey`
+ * (引擎铸的 `ordinal:specIdentityHash`)、判决词二选一。
+ * 🔴 **[ref] 之后这条纪律不再需要一条「别内插 label」的特判**:出身实体换成了记录上的 `parks[]` 条目,
+ * 而那是一只 **KEYS ONLY** 的对象(`callKey` / `sessionId` / `token` / `originRunId`,core 顶注逐字),
+ * 结构上就没有 LLM 撰写的位可插。人要读 label,读面已经有了(`GET /v1/workflows/:id` 的 agents[].label,
+ * 那条既有投影带脱敏);这里**不**再铸第二份清洗——少一条规则,而不是多一条。
  *
- * ## 答词 → 应答(闭集,`switch` 穷尽;引擎加词 ⇒ 编译红)
- *  · `driving`        —— 驱动起步 ⇒ 200 {@link parkedChildResumedReceipt}(**无**结清证据:resolve CAS 在驱动里才发生,本回执证不出提交);回执记进
- *                        {@link LIVE_REDEEM_RECEIPTS}(寿命 = 这条 run 在本进程里活着),供同一决定重点一次时回放;
- *  · `already_taken`  —— 这条 run 先前已收下这张卡的一个决定(驱动可能还在等并发槽,卡此刻仍 pending)⇒ 簿里同一决定(指纹相等)⇒ 原样回放首张回执;
- *                        否则(另一个决定)⇒ 409 `decide.claim_lost`(与后台子代并发决断同码);
- *  · `settled`        —— 卡在本次决断之下已离开 pending(到期 / 别处结清),这个决定没被用上(那一调以 `workflow.park_not_pending` 失败)⇒
- *                        409 `decide.gate_moved`(后台子代对同一事实的既有答;答 200 = 把「卡已到期」说成「你的批准已受理」);
- *  · `not_parked_here`—— 这条 run 此刻不在这张卡上等(正在收场 / 一个并发决断正拿着它)⇒ 409 `decide.gate_moved`;
- *  · `unreadable`     —— checkpoint 店的字此刻读不出,停驻原样留下 ⇒ 503 `decide.store_unreachable`(重试);
- *  · `kept_parked`    —— 只在送的是确认时可达 ⇒ 400 `decide.parked_restatement_unsupported`;送的是决定时引擎不会答它 ⇒ 抛(500);
- *  · `not_armed`      —— run 没有 checkpoint 座就不可能停驻出这张卡 ⇒ 抛(500,引擎不变量破;不猜一条去路)。
+ * 🔴 **为什么点名「同一份脚本源」**([ref] 真跑撞获,亲读 core 后成文):`resumeFromRunId` **不是**
+ * 自足入参 —— 安装的 core `dist/orchestration/run-workflow-tool.js` 在解析完 scriptPath/script/name
+ * 三选一之后就 `structuredError("Must provide script, name, or scriptPath")`(那一臂对带不带
+ * `resumeFromRunId` 一视同仁),它的 schema 描述逐字也是「resume a PRIOR run of the **SAME script**」。
+ * 修前这句话只说 `resumeFromRunId`,照着念的宿主会拿到那条结构化错误,而这条车道**是**这条审批唯一的
+ * 投递腿 ⇒ 决定送到了、兑不出来。文本是两条腿(wake / fresh)共用的那一份,改在这里 = 改在唯一属主上。
  */
-export type WorkflowLiveDelivery = {
-    readonly kind: "answered";
-    readonly answer: ParkedDecideResult;
-} | {
-    readonly kind: "resume_lane";
+export declare function workflowParkGuidance(runId: string, callKey: string, decision: "approve" | "deny"): {
+    text: string;
+    trusted: true;
 };
-/** 交给活 run 的那一次决定(计划已过两只拒臂;`fingerprint` = 决定行的同一只同一性判据 `parkDecisionFingerprint`,含重述键)。 */
-export interface WorkflowLiveDecision {
+/** 交给持有这张卡的那条 run 的一次决定(计划已过两只拒臂)。 */
+export interface WorkflowHolderDecision {
     readonly token: CheckpointToken;
     readonly outcome: WorkflowParkOutcome;
     readonly decision: "approve" | "deny";
-    readonly fingerprint: string;
-    readonly restated: boolean;
 }
-/** 一条活 run 的身份 + 它在本进程里收场的那一刻(读法 = 引擎的观察通道走完;run 不在本进程里跑 ⇒ 立即落定)。 */
-export interface HoldingRun {
-    readonly id: string;
-    readonly ended: () => Promise<void>;
-}
-/** 把决定交给持有这张卡的活 run(律见 {@link WorkflowLiveDelivery})。 */
-export declare function deliverToHoldingRun(origin: Extract<ParkOrigin, {
-    kind: "workflow";
-}>, d: WorkflowLiveDecision): Promise<WorkflowLiveDelivery>;
-/** 引擎的答 → 这次决断的应答(纯读法 + 回执簿;`suspending` 等它的 `ended` 落定)。导出给答词表的钉。 */
-export declare function answerOfParkDelivery(delivery: WorkflowParkDelivery, run: HoldingRun, d: WorkflowLiveDecision): Promise<WorkflowLiveDelivery>;
+/**
+ * 🔴 **把行上的决定交给引擎的唯一调用点**(`redeemWorkflowParks`,引擎对「这张停驻怎么处置」的唯一读法):两个调用方 —— 记录栅栏立住之后 `/decide` 的本进程快路
+ * ({@link answerOfHolderRedeem})与持有进程的拉取腿({@link holderPullDisposition})。恒送一个**决定**(`{ token, outcome }`):重述键在记录栅栏里判(`restated` 结局),
+ * 不再送引擎的确认动词去探「活不活」。引擎只查本进程:run 不在这里跑 ⇒ `not_active`(决定行已立住,交付归持有进程的拉取或收场送达)。
+ */
+export declare function redeemHere(runId: string, scope: string, d: Pick<WorkflowHolderDecision, "token" | "outcome">): Promise<WorkflowParkDelivery>;
+/**
+ * 记录栅栏三只零写拒结局 → 应答(闭集;`stands` / `not_running` 不在本表:前者进 {@link answerOfHolderRedeem},后者走续跑车道)。码全是既有码。
+ *  · `not_held`       —— run 仍在跑,已不持有这张卡(改停驻 / 已被驱动)⇒ 409 `decide.gate_moved`;
+ *  · `restated`       —— 决断带 `mcpServers` / `a2aPeers`,而持有它的 run 仍在跑(子代带着 run 已有的表继续)⇒ 400 `decide.parked_restatement_unsupported`,卡留 pending;
+ *  · `other_decision` —— 行上已是另一个决定(先受理者立)⇒ 409 `decide.claim_lost`。
+ */
+export declare function answerOfHolderFence(verdict: Exclude<HolderFenceVerdict, "stands" | "not_running">, runId: string): ParkedDecideResult;
+/** 记录栅栏这一段店没答出来(读记录 / 落行 / 锁定读)⇒ 503 `decide.store_unreachable`:什么都没决,持有这张卡的 run 照旧等着,重试。 */
+export declare function holderFenceFaultAnswer(runId: string): ParkedDecideResult;
+/**
+ * **记录栅栏立住之后,`/decide` 的本进程快路**:引擎对 {@link redeemHere} 的答 → 这次决断的应答(闭集,`switch` 穷尽;引擎加词 ⇒ 编译红)。
+ * 决定已在唯一仲裁点上立住 ⇒ 除「卡在本次决断之下已离开 pending」外,一律答同一张 200 回执({@link parkedChildResumedReceipt},无结清证据);本口**不**再等 `ended`、
+ * **不**再起续跑车道 —— 写了行的一方从不起宿主一跑,交付由持有进程的拉取(下一个维护拍)或 run 的收场送达完成。
+ *  · `live`/`driving`、`live`/`already_taken` ⇒ 200(单一仲裁之下,run 收下过的只可能是这同一个决定);
+ *  · `live`/`settled` ⇒ 409 `decide.gate_moved`(卡已离开 pending,这个决定没被用上;行惰性 —— 读者只供 pending 卡);
+ *  · `not_active`、`suspending`、`live`/`not_parked_here`、`live`/`unreadable` ⇒ 200(run 在别处跑 / 正在收场 / 本进程此刻读不出卡:行立住了,交付在后);
+ *  · `live`/`kept_parked` ⇒ 抛(送的是决定,引擎只对确认答它);`not_armed` ⇒ 抛(run 没有 checkpoint 座就停驻不出这张卡,引擎不变量破)。
+ * 「收场窗」的判放在管道事实上:run 收场之后由收场送达把行交给续跑车道,本表不读 `not_active` 的字面去区分「在别处跑」与「本进程收场中」。
+ */
+export declare function answerOfHolderRedeem(delivery: WorkflowParkDelivery, runId: string, decision: "approve" | "deny"): ParkedDecideResult;
+/**
+ * 持有进程的拉取腿对 {@link redeemHere} 的答的处置(闭集,`switch` 穷尽):
+ *  · `delivered` —— `driving` / `already_taken` / `settled`:引擎收下了(或卡已离开 pending、行惰性);
+ *  · `next_beat` —— `not_parked_here` / `unreadable`:此刻交不进去,行留着,下一拍再来;
+ *  · `left`      —— `suspending` / `not_active`:run 正在收场 / 已不在本进程,交付归 run 的收场送达;
+ *  · 抛          —— `kept_parked` / `not_armed`(与 {@link answerOfHolderRedeem} 同两只不变量)。
+ */
+export type HolderPullDisposition = "delivered" | "next_beat" | "left";
+export declare function holderPullDisposition(delivery: WorkflowParkDelivery, runId: string): HolderPullDisposition;
+/**
+ * 引擎的观察通道走完 = 这条 run 在本进程里收场了(`subscribeWorkflow` 在 run 收场的最后一步关闭;不在本进程里跑的 run 一开始就是空的 ⇒ 立即落定)。
+ * 三个读者:持有进程的视图(执行器寿命,`workflow-park-holder.ts`)、续跑车道开跑之前那一等(收场窗里引擎答 `not_active` 而 run 仍登记在跑,
+ * 宿主一跑的续跑会撞 fork 守卫 ⇒ 先等它走完)。core 的观察队列只关不拒。
+ */
+export declare function runChannelEnded(runId: string, scope: string): Promise<void>;
 /**
  * `/decide` parked 赎回腿([ref] 件3d server 半场;[ref]/[ref]/[ref] core 裁定形)。
  *