@sema-agent/client-core 0.62.2 → 0.63.1

package/dist/toolRoster.js

@@ -0,0 +1,236 @@
+/**
+ * src/toolRoster.ts — 一条腿的**工具名册**(`wiring_manifest.tools: ToolRoster`)窄读器 +
+ * `tool_roster_delta` 应用(0.63.0;L-161;engine >=7.66.0 有臂 / >=7.9.0 真推 /
+ * sdk 8.6.0 型面 + 8.7.0 `pathTarget` 三键)。
+ *
+ * -- 名册回答的是三端一直在猜的那一问 --------------------------------------------------------
+ * 「这条腿到底挂了哪些工具、每一只是什么面」此前只能猜:`liveInitToolFace.ts` 那三张词表
+ * (`ENGINE_HANDS_BAND` / `ENGINE_SCENARIO_EXTRAS_DEFAULT` / `ENGINE_RUNNER_FACE`)是 2026-07-16
+ * 一次 tap 实测的**估计值**,按 pin 的引擎版本定稿;外接别的引擎、别的场景、别的 env 门就会偏。
+ * 名册是**引擎自己说的**:每只工具的身份(契约 id / 形状指纹 / 能力 id)、轴(effect / egress /
+ * irreversibility)、面(family / pathTarget / renderHints)。
+ * 🔴 **名册在场用名册,缺席才回落三表**。本批**不删**那三张表(名册只在 effective 半场、且只有
+ *    >=7.9.0 的引擎才真推,回落还得留着);`liveInitToolFace.ts` 的头注登记了退役条款:
+ *    **名册恒在场的版本到货即删表**。
+ *
+ * -- 🔴 绝不半张名册(照抄上游的纪律)--------------------------------------------------------
+ * 引擎的 fail-open 台账逐字写着:载荷过不了 core 自己的判形器 => 那一段缺席 / 那一帧不发,
+ * **绝不半张脸上 wire**;并写明反方向更坏 ——「把一份判不了形的名册照发,消费端会把读不出的行
+ * 当成**这只工具没挂**」。本窄读器照抄这条:**任一行读不出 => 整只 `undefined`**;`count` 与真实
+ * 行数对不上同理(core 在铸点 run-time 断言两者相等)。少几行的名册比没有名册坏。
+ * ⚠️ 例外只有**面**:一行的 `pathTarget` / `renderHints` 自己形坏时只丢那一格,行还在 —— 面不是
+ *    身份,丢一张面不等于「这只工具没挂」。
+ *
+ * -- 🔴 `fromDigest` 对不上**不是拒绝** ------------------------------------------------------
+ * 契约里唯一的硬话:`fromDigest` 对不上时,**携带的整只名册无论如何都是新状态**,只有 `summary`
+ * 变得不可用(消费端记一次 skew 后按快照重同步)。所以 {@link applyToolRosterDelta} 在 skew 时
+ * **照换名册、只丢 summary**。拒绝换会让消费端永远抱着一份过期名册 —— 那比一次 skew 坏得多,
+ * 而且它把「位置从名册来、永远不从 summary 来」这条契约反过来用了。
+ *
+ * -- 开集读 -----------------------------------------------------------------------------------
+ * `source`(七词)/ `effect` / `family` / `access` 等词表的属主都是引擎,一律**原样透传**,不窄读成
+ * 枚举 —— 那会在引擎加词当天把一份真名册判没。
+ */
+const str = (v) => typeof v === 'string' && v.length > 0 ? v : undefined;
+const strArr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === 'string') : undefined;
+const obj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v) ? v : undefined;
+/** 指纹判据:**恰** 16 位小写 hex(引擎铸的就是这个形;放宽会让一个坏锚看起来能用)。 */
+const DIGEST_RE = /^[0-9a-f]{16}$/;
+function readPathTarget(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const param = str(o.param);
+    const access = str(o.access);
+    // 两必填键读不出 => 这张面不成形。**只丢面,不丢行**(面不是身份)。
+    if (param === undefined || access === undefined)
+        return undefined;
+    const aliases = strArr(o.aliases);
+    const base = str(o.base);
+    const absent = str(o.absent);
+    const patternParam = str(o.patternParam);
+    return {
+        param,
+        access,
+        ...(aliases !== undefined ? { aliases } : {}),
+        ...(o.skillScopeEligible === true ? { skillScopeEligible: true } : {}),
+        ...(base !== undefined ? { base } : {}),
+        ...(absent !== undefined ? { absent } : {}),
+        ...(patternParam !== undefined ? { patternParam } : {}),
+    };
+}
+function readEntry(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const name = str(o.name);
+    const source = str(o.source);
+    // 身份两键读不出 => 这一行不成形 => 由调用方把**整只名册**判没(见模块顶注)。
+    if (name === undefined || source === undefined)
+        return undefined;
+    const originRaw = obj(o.origin);
+    const peer = originRaw !== undefined ? str(originRaw.peer) : undefined;
+    const declaredBy = originRaw !== undefined ? str(originRaw.declaredBy) : undefined;
+    const contractRaw = obj(o.contract);
+    const contractId = contractRaw !== undefined ? str(contractRaw.contractId) : undefined;
+    const implementationRevision = contractRaw !== undefined ? str(contractRaw.implementationRevision) : undefined;
+    const hintsRaw = obj(o.renderHints);
+    const ruleFaceRaw = obj(o.ruleFace);
+    return {
+        name,
+        source,
+        ...(strArr(o.aliases) !== undefined ? { aliases: strArr(o.aliases) } : {}),
+        ...(peer !== undefined
+            ? { origin: { peer, ...(declaredBy !== undefined ? { declaredBy } : {}) } }
+            : {}),
+        ...(contractId !== undefined
+            ? { contract: { contractId, ...(implementationRevision !== undefined ? { implementationRevision } : {}) } }
+            : {}),
+        ...(str(o.shapeDigest) !== undefined ? { shapeDigest: str(o.shapeDigest) } : {}),
+        ...(str(o.wireSchemaDigest) !== undefined ? { wireSchemaDigest: str(o.wireSchemaDigest) } : {}),
+        ...(str(o.cardId) !== undefined ? { cardId: str(o.cardId) } : {}),
+        ...(str(o.capabilityId) !== undefined ? { capabilityId: str(o.capabilityId) } : {}),
+        ...(str(o.effect) !== undefined ? { effect: str(o.effect) } : {}),
+        ...(typeof o.egress === 'boolean' ? { egress: o.egress } : {}),
+        ...(str(o.irreversibility) !== undefined ? { irreversibility: str(o.irreversibility) } : {}),
+        ...(str(o.contentOrigin) !== undefined ? { contentOrigin: str(o.contentOrigin) } : {}),
+        ...(str(o.family) !== undefined ? { family: str(o.family) } : {}),
+        ...(readPathTarget(o.pathTarget) !== undefined
+            ? { pathTarget: readPathTarget(o.pathTarget) }
+            : {}),
+        ...(hintsRaw !== undefined
+            ? {
+                renderHints: {
+                    ...(str(hintsRaw.userFacingName) !== undefined ? { userFacingName: str(hintsRaw.userFacingName) } : {}),
+                    ...(str(hintsRaw.activity) !== undefined ? { activity: str(hintsRaw.activity) } : {}),
+                    ...(strArr(hintsRaw.summaryParams) !== undefined ? { summaryParams: strArr(hintsRaw.summaryParams) } : {}),
+                    ...(strArr(hintsRaw.resultCards) !== undefined ? { resultCards: strArr(hintsRaw.resultCards) } : {}),
+                    ...(str(hintsRaw.approvalCard) !== undefined ? { approvalCard: str(hintsRaw.approvalCard) } : {}),
+                },
+            }
+            : {}),
+        ...(ruleFaceRaw !== undefined
+            ? {
+                ruleFace: {
+                    ...(strArr(ruleFaceRaw.primaryParams) !== undefined ? { primaryParams: strArr(ruleFaceRaw.primaryParams) } : {}),
+                    ...(strArr(ruleFaceRaw.params) !== undefined ? { params: strArr(ruleFaceRaw.params) } : {}),
+                },
+            }
+            : {}),
+    };
+}
+/** 一只**已经剥出来**的名册体(不带 `tools` 包层)→ 视图;坏形 => `undefined`。 */
+function readRoster(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const digest = typeof o.digest === 'string' && DIGEST_RE.test(o.digest) ? o.digest : undefined;
+    if (digest === undefined)
+        return undefined;
+    if (!Array.isArray(o.entries))
+        return undefined;
+    if (typeof o.count !== 'number' || !Number.isInteger(o.count) || o.count < 0)
+        return undefined;
+    // 🔴 count 是引擎在铸点 run-time 断言过的量;对不上 => 这份载荷在路上被改过或被半截序列化。
+    if (o.count !== o.entries.length)
+        return undefined;
+    const entries = [];
+    for (const raw2 of o.entries) {
+        const e = readEntry(raw2);
+        // 🔴 绝不半张名册:一行读不出 => 整只判没(见模块顶注)。
+        if (e === undefined)
+            return undefined;
+        entries.push(e);
+    }
+    const schemaVersion = typeof o.schemaVersion === 'number' && Number.isFinite(o.schemaVersion) ? o.schemaVersion : 1;
+    return { schemaVersion, count: o.count, digest, entries };
+}
+/**
+ * `wiring_manifest` 的 `tools` 段 → 名册视图;整段缺席 / 任一行读不出 / `count` 对不上 =>
+ * `undefined`,绝不抛出。
+ *
+ * ⚠️ **空名册是正面事实**(这条腿一只工具都没挂),照读成 0 行 —— 与 `wiring_manifest.mcp[]` 的
+ *    空数组同一条已定谳的纪律,把它折成缺席等于把引擎明说的一句话读成「不知道」。
+ * ⚠️ 只在 **effective 半场**(live 帧)才有;诊断端点返回的 `static` 半场恒无 —— 那里的缺席是
+ *    结构性的,不是「这台引擎太老」。
+ */
+export function projectToolRoster(manifest) {
+    const o = obj(manifest);
+    if (o === undefined)
+        return undefined;
+    if (!('tools' in o))
+        return undefined;
+    return readRoster(o.tools);
+}
+/** 名册里的工具名,**按声明序**(= 模型看到的 `tools[]` 序)。 */
+export function toolRosterNames(roster) {
+    return roster?.entries.map((e) => e.name) ?? [];
+}
+/** 名册的一行 → 端用的面。行不成形(身份两键读不出)=> `undefined`,绝不抛出。 */
+export function toolShimFromRoster(entry) {
+    const e = readEntry(entry);
+    if (e === undefined)
+        return undefined;
+    return {
+        name: e.name,
+        source: e.source,
+        ...(e.family !== undefined ? { family: e.family } : {}),
+        ...(e.renderHints?.userFacingName !== undefined ? { userFacingName: e.renderHints.userFacingName } : {}),
+        ...(e.renderHints?.activity !== undefined ? { activity: e.renderHints.activity } : {}),
+        ...(e.renderHints?.approvalCard !== undefined ? { approvalCard: e.renderHints.approvalCard } : {}),
+        ...(e.renderHints?.summaryParams !== undefined ? { summaryParams: e.renderHints.summaryParams } : {}),
+        ...(e.effect !== undefined ? { effect: e.effect } : {}),
+        ...(e.egress !== undefined ? { egress: e.egress } : {}),
+        ...(e.irreversibility !== undefined ? { irreversibility: e.irreversibility } : {}),
+        ...(e.pathTarget?.param !== undefined ? { pathTargetParam: e.pathTarget.param } : {}),
+        ...(e.origin?.peer !== undefined ? { peer: e.origin.peer } : {}),
+        ...(e.cardId !== undefined ? { cardId: e.cardId } : {}),
+        ...(e.capabilityId !== undefined ? { capabilityId: e.capabilityId } : {}),
+    };
+}
+function readSummary(raw) {
+    const o = obj(raw);
+    if (o === undefined)
+        return undefined;
+    const added = strArr(o.added);
+    const removed = strArr(o.removed);
+    const changed = strArr(o.changed);
+    if (added === undefined || removed === undefined || changed === undefined)
+        return undefined;
+    // 数组里混进非串时 `strArr` 会静默滤掉 —— 那等于交一份少了名字的名单,与「绝不半张」同罪。
+    if (!Array.isArray(o.added) || added.length !== o.added.length ||
+        !Array.isArray(o.removed) || removed.length !== o.removed.length ||
+        !Array.isArray(o.changed) || changed.length !== o.changed.length) {
+        return undefined;
+    }
+    // 契约:三张名单**互不相交**。交了集就是坏 summary。
+    const all = [...added, ...removed, ...changed];
+    if (new Set(all).size !== all.length)
+        return undefined;
+    return { added, removed, changed };
+}
+/**
+ * `tool_roster_delta` → 新的持有状态。**纯函数**(不改入参)。
+ *
+ * 🔴 `fromDigest` 对不上**不是拒绝**(契约里唯一的硬话):携带的整只名册无论如何都是新状态,
+ *    只有 `summary` 变得不可用。拒绝换会让消费端永远抱着一份过期名册 —— 比一次 skew 坏得多。
+ * 🔴 手上**没有**名册(首帧就是 delta)同样算 `skew`:没有可比的 digest 就是比不出来,而
+ *    「比不出来」不许被读成「对上了」。
+ * 🔴 帧本身判不出形 => **什么都没发生**:原样交回入参那一份(不清空 —— 清空会把一次读不懂的帧
+ *    变成一次「所有工具都没挂」)。
+ */
+export function applyToolRosterDelta(held, delta) {
+    const d = obj(delta);
+    const next = d !== undefined ? readRoster(d.roster) : undefined;
+    if (d === undefined || next === undefined || typeof d.fromDigest !== 'string') {
+        return { roster: held, applied: false, skew: false };
+    }
+    const skew = held === undefined || held.digest !== d.fromDigest;
+    const summary = skew ? undefined : readSummary(d.summary);
+    return {
+        roster: next,
+        applied: true,
+        skew,
+        ...(summary !== undefined ? { summary } : {}),
+    };
+}

package/dist/workflow.js

@@ -96,7 +96,10 @@ export function projectWorkflowTaskOutput(jsonSrc) {
                 if (!r || typeof r !== 'object')
                     continue;
                 const label = typeof r.label === 'string' && r.label.length > 0 ? r.label : '(agent)';
-                const st = typeof r.status === 'string' ? r.status : '?';
+                // 🔴 与 `parseWorkflowPollEnvelope` **同一判**(0.63.1,G-20 附带②):同一条 wire 上的
+                //    同一个字段,两条链路的「在场」判据必须同形。空串走 `typeof` 单门会被当成一个读数
+                //    渲成 `[]` —— 一对什么也没说的方括号,还长得像一个真答案。空串 = 缺席。
+                const st = typeof r.status === 'string' && r.status.length > 0 ? r.status : '?';
                 const errLine = typeof r.error === 'string' && r.error.length > 0
                     ? ` — ${r.error.split('\n')[0].slice(0, 120)}`
                     : '';

package/dist/workflowClient.js

@@ -67,9 +67,23 @@ import { hostLog } from './host.js';
 // (workflowMonitor.ts) is the 187-faithful consumed set. We read the known fields, coerce
 // the vocabularies, and fill the shell-local render defaults the wire does not carry — same discipline as
 // projectTasks/projectWorkflows in fleet/fleetProjection.ts.
+/**
+ * ── `parked` 在这一族投影里的纪律(0.63.1;G-20)────────────────────────────────────────────
+ * 「停在审批门上」是一个**说得出口的状态词**,不是一个未知的未来值:那条腿在有人做决定之前
+ * **永远不会**自己往前走一步,而 `running` 承诺的恰恰是「等着就好」。⇒ 下面四处窄读一律给它
+ * 一条**自己的臂**,开集兜底(未知未来值 → 活跃)一个字节都不动。
+ *
+ * 三级词表今天各自的真实供给(engine core 7.10.0,亲核):
+ *   · **agent 行** —— `WorkflowItemStatus` 含 `parked`(#642),`deriveAgentDisplayStatus` 直接产
+ *     `"parked"`(`AgentDisplayStatus` 六词)⇒ 这是**今天就会到**的读数。
+ *   · **run 级** —— 仍闭在 running|completed|failed;一条腿 park ⇒ 整只 run 按
+ *     `WorkflowAgentParkedError` 收在 `failed` ⇒ `parked` 今天到不了这一位,那条臂是**前向预挂**。
+ *   · **phase 级** —— 上游明说「a phase or group never parks」,同为前向预挂;本包另从桶里的腿
+ *     **推**出这一格(见 `projectPhases`)。
+ */
 /** run status → the monitor's run-level vocabulary. SDK: queued|running|completed|failed|(open). The monitor
- *  run status is running|done|failed|stopped|paused — there is no run-level 'queued', so a queued run reads as
- *  'running' (the header shows the raw status text anyway; the box treats non-done/failed as active). */
+ *  run status is running|done|failed|stopped|paused|parked — there is no run-level 'queued', so a queued run
+ *  reads as 'running' (the header shows the raw status text anyway; the box treats non-done/failed as active). */
 function coerceRunStatus(s) {
     switch (s) {
         case 'completed':
@@ -78,6 +92,8 @@ function coerceRunStatus(s) {
             return 'failed';
         case 'running':
             return 'running';
+        case 'parked':
+            return 'parked'; // 前向预挂(见上方族头注):词真到了就原样透出,绝不折成「在跑」
         default:
             return 'running'; // queued / unknown-future → render as an active run (open-set fallback)
     }
@@ -94,6 +110,8 @@ function coercePhaseStatus(s) {
         case 'queued':
         case 'pending':
             return 'not-started';
+        case 'parked':
+            return 'parked'; // 前向预挂,同 coerceRunStatus
         default:
             return 'running';
     }
@@ -123,6 +141,11 @@ function coerceAgentState(s) {
         // !workflowActive — the run IS terminal whenever core emits this).
         case 'interrupted':
             return 'inactive';
+        // 🔴 core 7.10.0 #642:这条腿耐久挂在一张审批卡上(行上记着 checkpoint token)。**今天就会到**
+        // 的读数(raw `status` 与 `displayStatus` 两条腿都会带),原词透出——折进 `progress` 就是把
+        // 「要人去批」渲成「等它跑完」。
+        case 'parked':
+            return 'parked';
         default:
             return 'progress'; // unknown-future live status → render as an active agent (open-set fallback)
     }
@@ -174,7 +197,10 @@ function projectAgent(row, index) {
     // queued|running|done|failed|interrupted) over the RAW record `status` (running|completed|failed): the raw
     // vocabulary carries no queued/interrupted arm — a queued agent's record status is literally 'running', so
     // coercing `row.status` alone rendered every queued agent as "Running" (the [840] parity gap).
-    const displayStatus = typeof rec.displayStatus === 'string' ? rec.displayStatus : undefined;
+    // 🔴 空串 = 缺席(0.63.1,G-20 同形存量⑤):`??` 只挡 null/undefined,一个空串的 `displayStatus`
+    //    会把 raw `status` 整个静默吃掉(`'' ?? row.status` === `''`)—— 那条腿真正的状态词连回落
+    //    这条路都走不到。与 `workflow.ts` 两条链路同尺:空串不是读数。
+    const displayStatus = typeof rec.displayStatus === 'string' && rec.displayStatus.length > 0 ? rec.displayStatus : undefined;
     const state = coerceAgentState(displayStatus ?? row.status);
     const activity = projectActivity(row.activity);
     const last = activity.length ? activity[activity.length - 1] : undefined;
@@ -276,10 +302,9 @@ function projectPhases(run, agents) {
     if (distinct.length > 0) {
         return distinct.map(title => {
             const bucket = agents.filter(a => a._phase === title);
-            const allDone = bucket.every(a => a.state === 'done');
             return {
                 title,
-                status: bucket.some(a => a.state === 'error') ? 'failed' : allDone ? 'done' : 'running',
+                status: bucketStatus(bucket),
                 doneCount: bucket.filter(a => a.state === 'done').length,
                 totalCount: bucket.length,
                 agents: bucket.map(stripPhase),
@@ -289,13 +314,45 @@ function projectPhases(run, agents) {
     return [
         {
             title: 'Workflow',
-            status: run.status === 'completed' ? 'done' : run.status === 'failed' ? 'failed' : 'running',
+            // 同形第二处(G-20):这条三元式与 `coerceRunStatus` 读的是同一位 run 状态,兜底也同形 ——
+            // 只修一处等于把病搬个家。`parked` 走 `coerceRunStatus` 的同一条臂,不在这里另写一遍判据。
+            status: synthPhaseStatus(run.status, agents),
             doneCount: agents.filter(a => a.state === 'done').length,
             totalCount: agents.length,
             agents: agents.map(stripPhase),
         },
     ];
 }
+/**
+ * 一桶腿 → 这一格的状态词。
+ *
+ * 🔴 `parked` 的判据是「**这一格里没有一条腿能自己往前走**」:全员不是完成就是停在门上,且至少有
+ *    一条真停着。混着还在跑的腿时**仍报 running** —— 那一格确实还在跑,渲成 parked 是另一个方向的谎。
+ * 🔴 `failed` 仍先判:一格里既有失败又有停着的腿时,先要人看的是那条失败的。
+ */
+function bucketStatus(bucket) {
+    if (bucket.some(a => a.state === 'error'))
+        return 'failed';
+    if (bucket.length > 0 && bucket.every(a => a.state === 'done'))
+        return 'done';
+    if (bucket.some(a => a.state === 'parked') && bucket.every(a => a.state === 'parked' || a.state === 'done')) {
+        return 'parked';
+    }
+    return 'running';
+}
+/** 合成 `Workflow` 单格(路径三:wire 既无结构化 phases 也无 agent 上的 phase 标)的状态词。
+ *  跟 run 走(同 {@link coerceRunStatus} 的臂),run 说不出 `parked` 时再从腿上推一次 —— 今天真正
+ *  会带 `parked` 的正是腿那一级,而路径三的这一格代表的就是整只 run 的全部腿。 */
+function synthPhaseStatus(runStatus, agents) {
+    if (runStatus === 'completed')
+        return 'done';
+    if (runStatus === 'parked')
+        return 'parked';
+    const derived = bucketStatus(agents);
+    if (derived === 'parked')
+        return 'parked';
+    return runStatus === 'failed' ? 'failed' : 'running';
+}
 /** THE projector: SDK `WorkflowRun` (client.workflows.get) → the monitor's `WorkflowRunState`. Pure/total —
  *  tolerates absent/permissive fields and never throws (the graceful-degrade contract lives above, in the
  *  source loop; this just maps a well-formed run). Exported for the mock-parity unit cross-check. */

package/dist/workflowMonitor.d.ts

@@ -14,8 +14,13 @@
  *    留在 TUI 的:`computeVisibleWindow`(滚动窗口数学 = 视口概念,端专属)、glyph/color 映射、
  *    以及整棵 JSX。壳侧 shim = 那个 tsx 改成从本包 re-export 这两样,自己不再定义。
  */
-export type AgentState = 'start' | 'progress' | 'queued' | 'done' | 'error' | 'inactive';
-export type DisplayStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped' | 'interrupted';
+export type AgentState = 'start' | 'progress' | 'queued' | 'done' | 'error' | 'inactive'
+/** sema 超集:这条腿耐久挂在一张审批卡上(engine core 7.10.0 #642)。见上方头注。 */
+ | 'parked';
+export type DisplayStatus = 'queued' | 'running' | 'done' | 'failed' | 'skipped' | 'interrupted'
+/** sema 超集:同上。🔴 端的 glyph/颜色映射是**穷尽形**,加这一词就必须同批加一条 case
+ *  (措辞按「waiting for approval」一类,别复用 running 的字与色)。 */
+ | 'parked';
 export interface WorkflowToolCall {
     name: string;
     summary?: string;
@@ -61,7 +66,10 @@ export interface WorkflowAgent {
 }
 export interface WorkflowPhase {
     title: string;
-    status: 'not-started' | 'running' | 'done' | 'failed';
+    /** 🔴 `parked` = 这一格里没有一条腿能自己往前走(全员不是完成就是停在审批门上)。见 `AgentState`
+     *  的同名头注;上游今天不给 phase 铸这个词(core:「a phase or group never parks」),本包这一位有两个
+     *  来路:①上游哪天真铸了 ⇒ 原词透出而不是折成 running;②本包从桶里的腿**推**出来。 */
+    status: 'not-started' | 'running' | 'done' | 'failed' | 'parked';
     doneCount: number;
     totalCount: number;
     agents: WorkflowAgent[];
@@ -73,7 +81,11 @@ export interface WorkflowRunState {
     summary?: string;
     script: string;
     scriptPath?: string;
-    status: 'running' | 'done' | 'failed' | 'stopped' | 'paused';
+    /** 🔴 `parked`(0.63.1,additive):**前向预挂** —— engine core 7.10.0 的 run 级词表仍闭在
+     *  running|completed|failed(一条腿 park ⇒ 整只 run 按 `WorkflowAgentParkedError` 收在 `failed`),
+     *  所以今天没有任何受支持的引擎在这一位上发 `parked`。留这条臂是为了「词真到了就原样透出」,
+     *  绝不是说它现在会到 —— 判「这条 run 停着等人批」今天要看**腿**那一级(见 `AgentState.parked`)。 */
+    status: 'running' | 'done' | 'failed' | 'stopped' | 'paused' | 'parked';
     cloud?: boolean;
     agentCount: number;
     totalTokens: number;
@@ -97,5 +109,9 @@ export interface WorkflowRunState {
  * fields on the active path. The AgentState type carries exactly this input set, so the type contract now
  * matches the atlas vocabulary 1:1 — the branches below consume only atlas input states and the output
  * DisplayStatus set + glyph/color mapping ($jn) is identical.
+ *
+ * 🔴 **`parked` 是这条规则上唯一的 sema 超集臂**(0.63.1):atlas 没有它,因为 CC 的编排里没有耐久
+ * 审批这一层。它**不派生**——上游直接铸这个词(engine core 7.10.0 #642 的 agent 行 `status` 与
+ * `deriveAgentDisplayStatus` 产物),这里只是不许把它折掉。臂的**位置**是承重的,理由写在分支处。
  */
 export declare function agentDisplayStatus(a: WorkflowAgent, workflowActive: boolean): DisplayStatus;

package/dist/workflowMonitor.js

@@ -29,6 +29,10 @@
  * fields on the active path. The AgentState type carries exactly this input set, so the type contract now
  * matches the atlas vocabulary 1:1 — the branches below consume only atlas input states and the output
  * DisplayStatus set + glyph/color mapping ($jn) is identical.
+ *
+ * 🔴 **`parked` 是这条规则上唯一的 sema 超集臂**(0.63.1):atlas 没有它,因为 CC 的编排里没有耐久
+ * 审批这一层。它**不派生**——上游直接铸这个词(engine core 7.10.0 #642 的 agent 行 `status` 与
+ * `deriveAgentDisplayStatus` 产物),这里只是不许把它折掉。臂的**位置**是承重的,理由写在分支处。
  */
 export function agentDisplayStatus(a, workflowActive) {
     if (a.state === 'done')
@@ -36,6 +40,12 @@ export function agentDisplayStatus(a, workflowActive) {
     // atlas: `state==="error"` → skipped?"skipped":"failed".
     if (a.state === 'error')
         return a.skipped ? 'skipped' : 'failed';
+    // 🔴 sema 超集臂,**位置承重**:必须在 `!workflowActive` 之前判。一条腿 park 之后 run 自己收在
+    //    `failed`(core `WorkflowAgentParkedError`)⇒ `workflowActive` 恒假 ⇒ 放到后面就永远被
+    //    `interrupted` 吃掉,而 interrupted 说的是「run 结束时它还没跑完」——那是一件**已经过去**的事,
+    //    parked 说的是「它还挂在那儿,等一个人做决定」,是一件**还能动手**的事。两句下一步不同。
+    if (a.state === 'parked')
+        return 'parked';
     // atlas `!t` (workflow not active) → interrupted (also the `inactive`-state landing).
     if (!workflowActive)
         return 'interrupted';