@sema-agent/server 7.142.0 → 7.144.0

package/dist/session-notify-door.js

@@ -0,0 +1,97 @@
+import { externalNotificationInboxEntry } from "./orchestration/workflow-completion-inbox.js";
+import { sameOccupant } from "./execution-placement.js";
+import { recordFailOpen } from "./observability/fail-open.js";
+export function createSessionNotifyDoor(io) {
+    async function recheck(target) {
+        if (io.headOf === undefined)
+            throw new Error("session notify door: the session store has no head read (headOf); the occupant cannot be re-checked before delivery");
+        const head = await io.headOf(target.sessionId);
+        if (head === undefined)
+            return { delivery: "withdrawn", reason: "gone" };
+        return sameOccupant(target.occupant, head) ? undefined : { delivery: "withdrawn", reason: "replaced" };
+    }
+    return {
+        async deliver(target, event) {
+            const liveTaskId = await io.activeTaskIdOf(target.sessionId).catch((e) => {
+                recordFailOpen("server.session-notify.active-run-read-failed", `sessionId=${target.sessionId} err=${e instanceof Error ? e.message : String(e)}`);
+                return undefined;
+            });
+            if (liveTaskId !== undefined && liveTaskId !== null && io.liveRuns.has(liveTaskId)) {
+                const withdrawn = await recheck(target);
+                if (withdrawn !== undefined)
+                    return withdrawn;
+                const live = io.liveRuns.get(liveTaskId);
+                if (live !== undefined) {
+                    try {
+                        await live.notify(event, { priority: "next" });
+                        return { delivery: "live" };
+                    }
+                    catch (e) {
+                        const code = e.code;
+                        if (typeof code === "string" && code.startsWith("notify."))
+                            return { delivery: "refused", code, message: e instanceof Error ? e.message : "invalid notification" };
+                    }
+                }
+            }
+            if (io.inbox === undefined)
+                return { delivery: "no_inbox" };
+            const withdrawn = await recheck(target);
+            if (withdrawn !== undefined)
+                return withdrawn;
+            await io.inbox.enqueue(externalNotificationInboxEntry(target.sessionId, target.occupant.owner ?? target.ownerlessEntryOwner, { task_type: "external", ...event }, Date.now()));
+            return { delivery: "parked" };
+        },
+    };
+}
+export function createBackgroundCompletionRelay(io) {
+    return (root) => (n) => {
+        void relayToRoot(io, root, n).catch((err) => io.logger.warn("background_completion_undelivered", { ...completionFields(root, n), reason: "relay_failed", error: err instanceof Error ? err.message : String(err) }));
+    };
+}
+async function relayToRoot(io, root, n) {
+    const undelivered = (reason, extra) => io.logger.warn("background_completion_undelivered", { ...completionFields(root, n), reason, ...extra });
+    const door = io.door();
+    if (door === undefined)
+        return undelivered("door_unbound");
+    const out = await door.deliver({ sessionId: root.sessionId, occupant: { owner: root.owner, incarnation: root.incarnation ?? undefined }, ownerlessEntryOwner: null }, completionEvent(n));
+    switch (out.delivery) {
+        case "live":
+        case "parked":
+            return;
+        case "refused":
+            return undelivered("refused", { code: out.code });
+        case "no_inbox":
+            return undelivered("no_inbox");
+        case "withdrawn":
+            return undelivered(withdrawnReason(out.reason));
+        default: {
+            const unhandled = out;
+            throw new Error(`unhandled session notify outcome: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function withdrawnReason(reason) {
+    switch (reason) {
+        case "gone":
+            return "root_gone";
+        case "replaced":
+            return "root_replaced";
+        default: {
+            const unhandled = reason;
+            throw new Error(`unhandled withdrawn reason: ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+function completionEvent(n) {
+    return {
+        task_id: n.task_id,
+        status: n.status,
+        summary: n.summary,
+        ...(n.result !== undefined ? { result: n.result } : {}),
+        ...(n.seq !== undefined ? { seq: n.seq } : {}),
+    };
+}
+function completionFields(root, n) {
+    return { sessionId: root.sessionId, taskId: n.task_id, taskType: n.task_type, status: n.status };
+}
+//# sourceMappingURL=session-notify-door.js.map

package/dist/session-sync.d.ts

@@ -46,7 +46,7 @@
 import type { StoreBackend } from "./plugins/store-backend.js";
 import { type SyncRelation } from "./session-sync-kernel.js";
 import { type SessionTreeEntry, type SessionRulesRecord, type FileHistoryError, type FileHistoryExport, type FileHistoryResult, type SessionPermissionRules, type StoredSessionRules, type SessionPolicyStore } from "@sema-agent/core";
-import type { ServiceFileHistoryStore, ServiceSessionPolicyStore, ResumeAnchorStore } from "./plugins/store-backend.js";
+import type { ServiceBlobExchange, ServiceFileHistoryStore, ServiceSessionPolicyStore, ResumeAnchorStore } from "./plugins/store-backend.js";
 /**
  * core 7.55.0 [ref] T2([ref]):一只会话的文件历史**读不全**(撕裂 / 读不出的边界、读不出的跟踪集 —— 店的 `exportHistory` 答 `{ ok: false }`,`adopt_failed`
  * 带店判的 `permanence`)。它**不是**「没有历史」:读成 `null` 的同步会把这只会话的全部 rewind 历史丢在路上、还答成功。会话同步的两只拉取口
@@ -67,20 +67,15 @@ export declare function exportedFileHistory(store: Pick<ServiceFileHistoryStore,
  *  Returned by {@link exportSessionManifest} (closes over the source store); consumed wherever a caller pulls
  *  content-addressed history bytes lazily (the live PUSH route's `importHistory` replay). */
 export type BlobGetter = (hash: string) => Promise<Uint8Array | undefined>;
-/** blob 两面(`putBlob` / `getBlob`)齐备的文件历史店(marker 门,不做名字探测:local 的引擎文件店带同名私有助手)。 */
-export type SyncBlobHistoryStore = ServiceFileHistoryStore & {
-    readonly syncBlobFaces: true;
-} & {
-    [P in "putBlob" | "getBlob"]-?: NonNullable<ServiceFileHistoryStore[P]>;
-};
 /**
- * 「这只文件历史店有没有 blob 两面」的**唯一**读法:marker `syncBlobFaces`(只有 SQL 两只店立它)∧ 两面在场。能力事实 `sessionSyncFileHistory`(capability-facts)
- * 与取值口 {@link blobGetterOf} 都读它 —— 事实说有,取值口就通到事实店的 `getBlob`;事实说没有,取值口恒空。
- * 名字探测(`store.getBlob?.…`)不可靠:core 的 local 文件店带与服务面同名的**私有**助手(同形 `putBlob` 已被 marker 挡过一次),名字探会错拿到它。
+ * 「这只文件历史店能不能交换 blob」的**唯一**读法:店的 `blobExchange` 组,经 core 的判官 `fileHistoryBlobExchangeOf` 读 —— 没有组 ⇒ `undefined`
+ * (core 的 local 文件店);整组 ⇒ 三只成员(判官已绑好);缺一员 / 组不是对象 / 店还带退役的标记词 ⇒ 判官拒(`config.invalid_argument`,响亮,不是「没有」)。
+ * 能力事实 `sessionSyncFileHistory`(capability-facts)与取值口 {@link blobGetterOf} 都读它 —— 事实说有,取值口就通到同一组的 `get`;事实说没有,取值口恒空。
+ * 返回型收窄到本仓的 {@link ServiceBlobExchange}:判官交回的是店自己那一组的成员(只绑定、不包装),店型声明的组就是那一型。
  */
-export declare function syncBlobFacesOf(store: ServiceFileHistoryStore): SyncBlobHistoryStore | undefined;
-/** 一只文件历史店自己的 blob 取值口({@link BlobGetter}):从 {@link syncBlobFacesOf} 派生 —— 有 blob 两面 ⇒ 绑在店上的 `getBlob`;没有(core 的 local 文件店)⇒ 恒答 `undefined`(「这里取不到」)。
- *  拉取面(manifest 的 `getBlob`)、identical 自愈臂、提交臂三处读同一只,不各写一份「无面则 undefined」。 */
+export declare function blobExchangeOf(store: ServiceFileHistoryStore): ServiceBlobExchange | undefined;
+/** 一只文件历史店自己的 blob 取值口({@link BlobGetter}):从 {@link blobExchangeOf} 派生 —— 有交换组 ⇒ 组的 `get`;没有(core 的 local 文件店)⇒ 恒答 `undefined`(「这里取不到」)。
+ *  拉取面(manifest 的 `getBlob`)、identical 自愈臂、提交臂三处读同一只,不各写一份「无组则 undefined」。 */
 export declare function blobGetterOf(store: ServiceFileHistoryStore): BlobGetter;
 /** The history-import capability face of a `FileHistoryStore` (`importHistory` is OPTIONAL on the core
  *  contract — a store without it cannot be a 2c history sink). */
@@ -123,7 +118,7 @@ export type FileHistoryReplayFailure = Extract<FileHistoryReplayResult, {
  * The alternative (keeping the old graph) would wedge every retry on the same typed conflict forever.
  *
  * 缺 blob 的事实只在这里读一次:每次尝试给店的 getter 都包一层观察,店取到 `undefined` 就记下那枚 hash(按次计,替换臂的第二次尝试从空白起),
- * 失败时随结果交出({@link FileHistoryReplayResult.missingBlob})。预检({@link sessionSyncFileHistory} 事实 + `hasBlobs`)管「这台部署根本收不到 / 索引里没有」,
+ * 失败时随结果交出({@link FileHistoryReplayResult.missingBlob})。预检({@link sessionSyncFileHistory} 事实 + 交换组的 `has`)管「这台部署根本收不到 / 索引里没有」,
  * 这里管「预检过了而这一枚取不到」(对象存储里已丢 / 校验和不符按缺席读 / 预检与重放之间被孤儿回收清走)—— 同一只不变量的两端,wire 上同一个词。
  */
 export declare function replayFileHistory(store: ServiceFileHistoryStore, scope: string, envelope: FileHistoryExport, srcGetBlob: BlobGetter, opts: {

package/dist/session-sync.js

@@ -2,7 +2,7 @@ import { anchorEntryDeclared, classifySyncRelationship } from "./session-sync-ke
 import { recordFailOpen } from "./observability/fail-open.js";
 import { loosenReasons, normalizeRules } from "@sema-agent/core";
 import { headReadOf } from "./session-incarnation.js";
-import { judgeSessionRulesWrite } from "@sema-agent/core";
+import { fileHistoryBlobExchangeOf, judgeSessionRulesWrite } from "@sema-agent/core";
 export class FileHistoryUnreadableError extends Error {
     sessionId;
     failure;
@@ -22,12 +22,12 @@ export async function exportedFileHistory(store, sessionId) {
         throw new FileHistoryUnreadableError(sessionId, exported.error);
     return exported.history;
 }
-export function syncBlobFacesOf(store) {
-    return store.syncBlobFaces === true && typeof store.putBlob === "function" && typeof store.getBlob === "function" ? store : undefined;
+export function blobExchangeOf(store) {
+    return fileHistoryBlobExchangeOf(store);
 }
 export function blobGetterOf(store) {
-    const faces = syncBlobFacesOf(store);
-    return faces ? (hash) => faces.getBlob(hash) : async () => undefined;
+    const exchange = blobExchangeOf(store);
+    return exchange ? exchange.get : async () => undefined;
 }
 export function fileHistoryImportFace(fs) {
     const candidate = fs?.importHistory;

package/dist/session-workspace.d.ts

@@ -11,7 +11,7 @@
  *    门在 `trace/core-keyset-guard.ts` ⑰ 读同一张表)。**唯一写者** = 腿的记录座 {@link createSessionWorkspaceRecorder}
  *    (持流的四条腿逐帧喂同一只;委派子代转上来的帧 —— 带 `parentToolCallId` / `sourceTaskId` / `bgAgentId` —— 不是这条腿的位置,不认)。
  *    每一笔写**在腿的流循环里等完**(不排队、没有在飞的写:腿从任何出口离开时都没有它的写还悬着 ⇒ 写恒落在这条腿的 run 认领之内,
- *    同一会话的下一条腿不会被一笔晚到的写盖掉),并且**只写受理时见证到的那一位住客**({@link stampLegSessionWitness}:resolveSpec
+ *    同一会话的下一条腿不会被一笔晚到的写盖掉),并且**只写受理时见证到的那一位住客**(这条腿的部署事实 `sessionWitness`,`leg-facts.ts`:resolveSpec
  *    受理时读会话行的化身那一读,同一只值也是委派树根的见证)—— 会话被删掉又以同一 id 重建之后,上一位住客的腿写不进新住客的行。
  *  · **每条腿声明一个值**:`TaskSpec.projectId` = 这次提交自己带的 `projectId`(新提交的请求体;续跑腿重放的是持久化的同一个体)
  *    ?? 会话行上最后一帧的 `project.id` —— **只当它是调用方声明过的**(`source: "declared"`:没有记号的检出里声明就是身份,行存它就是为了接着声明);
@@ -34,7 +34,7 @@
  *  · **行读在 run 认领之前**(resolveSpec 的每一读都是):同一会话两次提交交叠、后一次的装配读行之后前一次才落定并放认领 ⇒ 后一次读到的是更早
  *    一条腿的项目(有记号的检出里多一次 409,没有记号的检出里续声明旧项目)。修法要把声明的装配挪到认领之后,不在本模块补第二个写者。
  */
-import type { TaskEvent, TaskSpec } from "@sema-agent/core";
+import type { TaskEvent } from "@sema-agent/core";
 import type { DelegationRootWitness } from "./delegated-session-owner.js";
 /**
  * `workspace_changed` 帧在会话行上的样子(**唯一**一张表;表序 = 存储形的键序)。`forward` = 原值存进行;`strip` = 不进行。
@@ -84,16 +84,6 @@ export interface SessionWorkspaceStore {
 }
 /** 店有没有这一面 —— 结构判(包装店 `CachingSessionStore` 逐方法转发,判的是能力不是名字)。没有 ⇒ 不记、不读(core 的内存 dev 店)。 */
 export declare function sessionWorkspaceStoreOf(store: unknown): SessionWorkspaceStore | undefined;
-/**
- * 这条腿的会话**在受理时**是哪一位住客(会话 id + 化身令牌)的 spec 字段键 —— 与 run 名册 / 执行车道字段同一形:symbol 键随 spread / rest 解构走
- * (续跑腿的 `taskConfig` 是 rest 解构出来的),对引擎的键面不可见(JSON / 结构化克隆跳过 symbol 键)。铸点唯一 = resolveSpec 出口
- * ({@link stampLegSessionWitness}),值 = 受理时读会话行的那**一**读(同一只值也交给场景层作委派树根的见证);读点唯一 = {@link legSessionWitnessOf}。
- */
-export declare const LEG_SESSION_WITNESS_FIELD: unique symbol;
-/** 铸见证(**单一属主**:只许 resolveSpec 的出口调用)。`writable:false` + `configurable:false`:同一只 spec 被第二次铸 ⇒ 当场 TypeError。缺席 ⇒ 不铸。 */
-export declare function stampLegSessionWitness<T extends TaskSpec>(spec: T, witness: DelegationRootWitness | undefined): T;
-/** 读见证。`undefined` = 这只 spec 不是本仓装配出口产的,或这条腿没有会话 ⇒ 记录座不写(没有住客可认)。入参收 `object`:续跑腿手里是 rest 解构出来的 taskConfig。 */
-export declare function legSessionWitnessOf(spec: object): DelegationRootWitness | undefined;
 /**
  * 一帧 → 会话行上那一格的值。只认这条腿**自己的**帧(腿身份三键任一在场 = 委派子代转上来的,不是这条腿站在哪里);
  * 按表投影后过存储形的同一只读者(写得进的就是读得出的)。读不出(引擎不会铸出这种帧)⇒ 不记、计一次。
@@ -109,7 +99,7 @@ export interface SessionWorkspaceRecorder {
 }
 /**
  * 记录座的**唯一**铸点(四条持流腿各在开流时铸一只:后台腿 `runs.ts`、活流腿与同步腿 `http/routes/tasks.ts`、续跑腿 `http/resume-legs.ts`),
- * `witness` = 这条腿 spec 上的受理见证({@link legSessionWitnessOf})。店没有这一面、或见证缺席 / 受理时这只会话还没有住客令牌 ⇒
+ * `witness` = 这条腿的受理见证(部署事实 `LegFacts.sessionWitness`,`leg-facts.ts`;嵌入方自带装配器 ⇒ 缺席)。店没有这一面、或见证缺席 / 受理时这只会话还没有住客令牌 ⇒
  * 一只什么都不做的座(诚实缺席:认不出住客就不写 —— 写错住客比少记一次坏)。
  *
  * 失败方向(F 类):写失败(库抖 / 盘满 / 锁等待超时)⇒ 行停在上一帧,计一次;下一帧照写。放行的最坏后果 = 下一条不带 `projectId` 的提交读到旧的

package/dist/session-workspace.js

@@ -19,15 +19,6 @@ export function sessionWorkspaceStoreOf(store) {
         return undefined;
     return { readSessionWorkspace: s.readSessionWorkspace.bind(s), recordSessionWorkspace: s.recordSessionWorkspace.bind(s) };
 }
-export const LEG_SESSION_WITNESS_FIELD = Symbol("sema-server.legSessionWitness");
-export function stampLegSessionWitness(spec, witness) {
-    if (witness !== undefined)
-        Object.defineProperty(spec, LEG_SESSION_WITNESS_FIELD, { value: Object.freeze({ ...witness }), enumerable: true, writable: false, configurable: false });
-    return spec;
-}
-export function legSessionWitnessOf(spec) {
-    return spec[LEG_SESSION_WITNESS_FIELD];
-}
 export function sessionWorkspaceOfFrame(ev) {
     if (ev.type !== "workspace_changed")
         return undefined;

package/dist/standing-answer-grant.d.ts

@@ -35,6 +35,11 @@ export type GrantBinding = {
 /** 载体上的授予绑定 —— 只读引擎的词(读法见文件头注):摘要是串 ⇒ bound;摘要不在且词是 `not_bindable` ⇒ none;其余 ⇒ unreadable。
  *  形参是任意对象(载体不论):读自持久层的停驻行(运维队列行的投影、`/decide` 的原始行)两座都按 `unknown` 读,结构上满足 {@link StandingAnswerCard} 的载体照传。 */
 export declare function grantBindingOf(card: StandingAnswerCard | object): GrantBinding;
+/**
+ * 同一只问的两份授予绑定读数取严(7.143.0;读者 = `tool-approval.ts` 幂等重入那一臂:这一腿的请求 × 行上记着的事实座)。
+ * 两份逐臂同 ⇒ 那一份;不同(含任一份 `unreadable`)⇒ `unreadable`(本会话放行记不住)。只收窄、永不放宽任一份。
+ */
+export declare function agreedGrantBinding(a: GrantBinding, b: GrantBinding): GrantBinding;
 /** 授予绑定在读面上的形:恰一臂 —— 摘要,或缺席词(闭集 core `BOUND_GRANT_ABSENCES`)。 */
 export type GrantBindingArm = {
     readonly boundGrantDigest: string;

package/dist/standing-answer-grant.js

@@ -7,6 +7,16 @@ export function grantBindingOf(card) {
     const word = "boundGrantAbsence" in card ? card.boundGrantAbsence : undefined;
     return digest === undefined && word === NOT_BINDABLE ? { kind: "none" } : { kind: "unreadable" };
 }
+export function agreedGrantBinding(a, b) {
+    switch (a.kind) {
+        case "none":
+            return b.kind === "none" ? a : { kind: "unreadable" };
+        case "bound":
+            return b.kind === "bound" && b.digest === a.digest ? a : { kind: "unreadable" };
+        case "unreadable":
+            return a;
+    }
+}
 export function grantBindingArm(binding) {
     switch (binding.kind) {
         case "bound":

package/dist/stores-sql/session-policy-store-sql.d.ts

@@ -86,8 +86,10 @@ export declare class SqlSessionPolicyStore implements SessionPolicyStore {
      *    `main`'s statement sequence, zero mark table involved): InnoDB 1 winner / 7 `ER_LOCK_DEADLOCK`, TiDB 0,
      *    PG 0 — i.e. this is a PRE-EXISTING MySQL-leg defect that [ref]'s lock-shape site made visible, not a new one.
      *    After the first insert commits, the retried writers find the row and take the UPDATE path (record lock,
-     *    no gap) ⇒ the loop converges in one extra round per missing-row window; the bound is the suite's concurrency.
-     *  Lock-WAIT-TIMEOUT is deliberately NOT retried ({@link isDeadlockError}'s own note: it is a latency signal,
+     *    no gap) ⇒ the loop converges in one extra round per missing-row window; the bound is the suite's concurrency
+     *    (a writer is picked at most once per missing-row window, and there are 1 + this round's erases of them) —
+     *    the repo's one bound, `DEADLOCK_RETRY_LIMIT`, owned with the loop itself by `retryOnDeadlock` in `sql-errors.ts`.
+     *  Lock-WAIT-TIMEOUT is deliberately NOT retried (`isDeadlockError`'s own note: it is a latency signal,
      *  and retrying it multiplies an already-long wait).
      */
     private retrying;

package/dist/stores-sql/session-policy-store-sql.js

@@ -4,10 +4,9 @@ import { SESSION_RULES_COLUMN } from "../plugins/session-rules-column.js";
 import { decodeJsonColumn, isJsonColumnBodyProblem, jsonColumnText } from "../plugins/sql-json-column.js";
 import { pgHasUnstorable } from "../plugins/pg-safe-json.js";
 import { mysqlDriver, pgDriver } from "../plugins/sql-driver.js";
-import { isDeadlockError, isDupKeyError } from "../plugins/sql-errors.js";
+import { isDupKeyError, retryOnDeadlock } from "../plugins/sql-errors.js";
 export const policyKeyFor = (sessionId, principal) => createHash("sha256").update(JSON.stringify([sessionId, principal ?? null])).digest("hex");
 const policyKey = policyKeyFor;
-const RETRY_LIMIT = 8;
 const RULES = SESSION_RULES_COLUMN.name;
 export function readSessionRulesBody(body) {
     const read = readSessionRulesShape(body);
@@ -129,17 +128,8 @@ export class SqlSessionPolicyStore {
             return structuredClone({ ...clean, rev: nextRev, gen: nextGen });
         }));
     }
-    async retrying(attempt) {
-        for (let tries = 0;; tries++) {
-            try {
-                return await attempt();
-            }
-            catch (e) {
-                if (tries < RETRY_LIMIT && (this.isDupKey(e) || isDeadlockError(this.db.dialect, e)))
-                    continue;
-                throw e;
-            }
-        }
+    retrying(attempt) {
+        return retryOnDeadlock(this.db.dialect, attempt, (e) => this.isDupKey(e));
     }
     async deleteBySession(sessionId) {
         const sealed = await this.retrying(() => this.tx(async (conn) => {

package/dist/task-mcp.d.ts

@@ -71,7 +71,7 @@ export declare const MCP_SERVER_ENTRY_KEYS: readonly ["allowTools", "contentOrig
 /** `transport.kind:"stdio"` 的键闭集 = stdio 臂处置表的键(`env` 是件,其余进声明)。 */
 export declare const STDIO_MCP_TRANSPORT_KEYS: readonly ("env" | "kind" | "args" | "command")[];
 /** `transport.kind:"http"` 的键闭集 = http 臂处置表的键(`headers` 是件,`assertionHeader` 承载不发送,其余进声明)。 */
-export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("headers" | "kind" | "url" | "principalHeader" | "assertionHeader")[];
+export declare const HTTP_MCP_TRANSPORT_KEYS: readonly ("headers" | "url" | "kind" | "principalHeader" | "assertionHeader")[];
 /**
  * Does THIS deployment honor caller-supplied per-request MCP servers? TRUE for a SINGLE-USER deployment
  * (deployment-shape row `multiTenant` does not hold) — the requester is the super-admin of their own worker, so their `.mcp.json` is

package/dist/task-settings.d.ts

@@ -15,7 +15,9 @@
  *  - `deny` / `ask` are folded via `tightenTaskSpec` (deny-wins `combinePolicies`); it THROWS on any override that would
  *    LOOSEN a stricter base safety field. Through those two buckets the client can only ADD denies / asks on top of the
  *    deployment + operator baseline.
- *  - `allow` (server 7.117.0, core 7.42.0) is NOT a policy: the list rides WHOLE and verbatim into `TaskSpec.allowedTools`,
+ *  - `allow` (server 7.117.0, core 7.42.0) is NOT a policy: the list rides WHOLE, one member per entry in the entry's position, into `TaskSpec.allowedTools`
+ *    (a string verbatim; a settings layer's `{ rule, layer }` entry as its rule text, or — when its `/` reads at the configuration root — as
+ *    `{ rule, pathBases: { root } }`, the same anchor its deny / ask twin's set declares: {@link allowMemberOf}),
  *    the request member of the engine's ONE allow layer (beside a deployment's `RunnerDeps.allowedTools`, a person's stored
  *    rows, an active skill's `allowed-tools` and a PreToolUse hook's `allow`), read under one predicate. It IS an accepted
  *    loosening for this run: an entry clears the `unstated` / `ordinary` questions the engine raises for the calls it covers
@@ -198,7 +200,8 @@ export declare function skillListingMaxDescOk(v: unknown): v is number;
  *  deferred (submit 路径另有 400 fail-loud),valid `hooks` 进 applied shape(hook-runner 阶段一)。 */
 export interface ParsedTaskSettings {
     permissions?: {
-        allow?: string[];
+        /** 与 `deny` 同一条目形(带层条目的层只选 `/` 的锚);投 `TaskSpec.allowedTools` 的唯一写点 {@link applyTaskSettings}。 */
+        allow?: RuleListEntry[];
         /** 纯串 = 请求自己写的规则;`{ rule, layer }` = 端从某个设置层读来的规则(`permission-rule-list.ts` 的 {@link RuleListEntry};层只选 `/` 的锚)。 */
         deny?: RuleListEntry[];
         /** 同 `deny` 的条目形;编译与 `deny` 同一口({@link deriveSettingsPolicy})。 */
@@ -297,8 +300,8 @@ export interface SettingsPermissionBucketIssue {
 /**
  * 三桶的**唯一**判据(纯函数)。`perms` 不是对象 ⇒ 不判(那一形归「settings.permissions must be an object」那道门);桶缺席 / `null`
  * ⇒ 不判(与 `permissions: null` 的「容器缺席」同一约定)。逐桶按 {@link SETTINGS_PERMISSION_BUCKETS} 的序、按该桶的条目规则:不是数组 ⇒ `bad_entry`
- * (无 `index`);`rule_policy` 桶超帽 ⇒ `over_cap`(先判,拒体有界)、首个不合条目律的项(不是非空串、也不是合形的带层条目)⇒ `bad_entry` + 它的下标;`allow_layer` 桶首个非串项 ⇒
- * `bad_entry` + 它的下标(整表判据 = `ruleEntryListShapeOk`),超帽同样 `over_cap`(帽的理由不同,见段头)。全合法 ⇒ `null`。
+ * (无 `index`);`rule_policy` 桶超帽 ⇒ `over_cap`(先判,拒体有界)、首个不合条目律的项(不是非空串、也不是合形的带层条目)⇒ `bad_entry` + 它的下标;`allow_layer` 桶首个既不是串、
+ * 也不是合形带层条目的项 ⇒ `bad_entry` + 它的下标,超帽同样 `over_cap`(帽的理由不同,见段头)。全合法 ⇒ `null`。
  */
 export declare function settingsPermissionBucketIssue(perms: unknown): SettingsPermissionBucketIssue | null;
 /** 本 service 真正**消费**的 `settings` 顶层键 —— 闭集。每一个都有消费点:
@@ -459,7 +462,7 @@ export interface FsWriteGateWiring {
     taskHome?: string;
     /**
      * **执行环境的配置根**(唯一属主 `execution-config-root.ts` 的 `executionConfigRootOf`):user 设置层里 `/` 形路径规则的根 —— 带 `layer: "userSettings"`
-     * 且要 `root` 的条目编进只声明 `{ root: configRoot }` 的那一集(`permission-rule-list.ts` 的 `ruleRootOf`)。缺席(沙箱车道既没转 `SEMA_CONFIG_DIR`、home 也读不出)
+     * 且要 `root` 的条目编进只声明 `{ root: configRoot }` 的那一集、allow 桶里的投成带同一声明的那一员(`permission-rule-list.ts` 的 `ruleRootOf`)。缺席(沙箱车道既没转 `SEMA_CONFIG_DIR`、home 也读不出)
      * ⇒ 这样的条目由 {@link rejectUnmatchableSettingsNames} 响亮拒(422 `home_unresolvable`),不猜目录。拒点与存体预判读同一只函数。
      */
     configRoot?: string;
@@ -486,7 +489,7 @@ export type RulePolicyBucket = (typeof RULE_POLICY_BUCKETS)[number];
 /**
  * deny / ask 两桶的**完整规则判**,唯一一只(拒点 {@link rejectUnmatchableSettingsNames} 与存体预判 `http/stored-body-replay.ts` 同调):
  *  ② 按 {@link RULE_POLICY_BUCKETS} 的序逐桶、桶内按 `RULE_ROOTS` 的序逐集(`permission-rule-list.ts` 的 `ruleSetsOf`:判的就是要编的那一集)问 `judgeUnmatchableToolNames`(名字层 + core 规则文法);
- *  ③ 再判「这条规则要的基本部署给不出」那一拒:`~/` 形缺 home;配置根那一集缺配置根(两者都落在执行环境的 home 上,同词 `home_unresolvable`)。答 `{ bucket, message, problems }`:`bucket` 与 `message` 是**第一处**坏处的
+ *  ③ 再判「这条规则要的基本部署给不出」那一拒:`~/` 形缺 home(deny / ask);配置根那一集缺配置根(三桶,{@link LAYER_ROOT_BUCKETS};两者都落在执行环境的 home 上,同词 `home_unresolvable`)。答 `{ bucket, message, problems }`:`bucket` 与 `message` 是**第一处**坏处的
  *  (句子冻结,先撞上的那一条),`problems` 是**两段、两只桶判下来的全部**坏条目(机读位的原料,形的属主 `entry-problems.ts`;`entry` = 规则原文,带层条目也一样)。
  * 入参:桶、{@link RulePolicyBases}。**home 同源**:拒点的 home 是 `resolve-spec.ts` 的 `laneHomeBase()` 经 `executionLaneHomeDir(config)` 算出的,预判传同一个函数对同一份部署配置算出的;配置根同理(`executionConfigRootOf`)。
  * **任务根那一集声明给文法的基**只有拒点有(根 + home 的并集,执行车道才知道根):core 的规则文法对**没声明**的基不下判词(见 `config.ts` `uncompilableRuleGuidance`),所以预判什么也不声明、两腿逐字同句;
@@ -502,8 +505,8 @@ export interface RulePolicyBases {
     /** 执行环境的配置根(配置根那一集的根;拒点与预判都给);读不出 ⇒ 缺席。 */
     readonly configRoot?: string;
 }
-export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<RulePolicyBucket, readonly RuleListEntry[]>>>, bases: RulePolicyBases): {
-    readonly bucket: RulePolicyBucket;
+export declare function rulePolicyBucketsRefusal(permissions: Readonly<Partial<Record<SettingsPermissionBucket, readonly RuleListEntry[]>>>, bases: RulePolicyBases): {
+    readonly bucket: SettingsPermissionBucket;
     readonly message: string;
     readonly problems: readonly EntryProblem[];
 } | undefined;

package/dist/task-settings.js

@@ -2,8 +2,8 @@ import { combinePolicies, parseRuleText, resolveReasoningProfile, rankOf, isThin
 import { judgeUnmatchableToolNames } from "./config.js";
 import { NAME_TABLE_BEHAVIOR } from "./namespaced-rule-name.js";
 import { entryProblem } from "./entry-problems.js";
-import { MAX_PERMISSION_RULES_PER_LIST, RULE_ROOTS, createRuleListPolicy, ruleListEntryOk, ruleSetsOf, ruleSourceOf, ruleTextOf } from "./permission-rule-list.js";
-import { allowLayerEntryCountIssue, describeAllowLayerOverCap, ruleEntryListShapeOk } from "./rule-entry-list.js";
+import { MAX_PERMISSION_RULES_PER_LIST, RULE_ROOTS, allowListEntryOk, createRuleListPolicy, ruleListEntryOk, ruleRootOf, ruleSetsOf, ruleSourceOf, ruleTextOf } from "./permission-rule-list.js";
+import { allowLayerEntryCountIssue, describeAllowLayerOverCap } from "./rule-entry-list.js";
 import { limitRefusal } from "./limit-refusal.js";
 import { tightenGoverned } from "./governance-overrides.js";
 import { MAX_KEY_ECHO, keyClosureClause, scanKeyClosure } from "./request-key-closure.js";
@@ -113,8 +113,8 @@ function bucketIssueMessage(f, rule) {
                         : `${f.field}[${f.index}] is neither a non-empty rule string nor a { "rule", "layer" } entry (exactly those two keys; rule = a non-empty rule string; layer = one of ${SETTINGS_SOURCES.join(", ")}) — every entry must be one. Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
                 case "allow_layer":
                     return f.index === undefined
-                        ? `${f.field} must be an array of permission-rule strings — refused rather than ignored, because an ignored list reads as "in effect" to the caller`
-                        : `${f.field}[${f.index}] is not a string — every entry must be a permission-rule string (a settings layer's { "rule", "layer" } entry is read in deny / ask only). Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
+                        ? `${f.field} must be an array of rule entries (a rule string, or { "rule": <rule>, "layer": <settings source> }) — refused rather than ignored, because an ignored list reads as "in effect" to the caller`
+                        : `${f.field}[${f.index}] is neither a rule string nor a { "rule", "layer" } entry (exactly those two keys; rule = a non-empty rule string; layer = one of ${SETTINGS_SOURCES.join(", ")}) — every entry must be one. Refused rather than dropped, because a dropped entry reads as "in effect" to the caller`;
             }
     }
 }
@@ -146,8 +146,11 @@ export function settingsPermissionBucketIssue(perms) {
                     const over = allowLayerEntryCountIssue(field, v);
                     if (over !== undefined)
                         fields = { field, reason: "over_cap", count: over.facts.count, cap: over.facts.cap };
-                    else if (!ruleEntryListShapeOk(v))
-                        fields = { field, reason: "bad_entry", index: v.findIndex((x) => typeof x !== "string") };
+                    else {
+                        const index = v.findIndex((x) => !allowListEntryOk(x));
+                        if (index >= 0)
+                            fields = { field, reason: "bad_entry", index };
+                    }
                     break;
                 }
             }
@@ -372,6 +375,7 @@ export class SettingsRuleRefusalError extends Error {
 }
 export const SETTINGS_RULE_REFUSAL_CODE = "request.unprocessable";
 export const RULE_POLICY_BUCKETS = ["ask", "deny"];
+const LAYER_ROOT_BUCKETS = [...RULE_POLICY_BUCKETS, "allow"];
 export function rulePolicyBucketsRefusal(permissions, bases) {
     let first;
     const problems = [];
@@ -423,7 +427,7 @@ export function rulePolicyBucketsRefusal(permissions, bases) {
         }
     }
     if (bases.configRoot === undefined) {
-        for (const bucket of RULE_POLICY_BUCKETS) {
+        for (const bucket of LAYER_ROOT_BUCKETS) {
             const field = `permissions.${bucket}`;
             for (const name of ruleSetsOf(permissions[bucket] ?? [], bucket).configuration.map(ruleTextOf)) {
                 first ??= {
@@ -443,9 +447,25 @@ function ruleSetBases(root, taskBases, configRoot) {
         case "task":
             return taskBases;
         case "configuration":
-            if (configRoot === undefined)
-                throw new Error("a user-settings path rule reached the compiler without a configuration root — the admission judgement refuses it first (home_unresolvable); refusing rather than anchoring it at the task root");
-            return { root: configRoot };
+            return configurationSetBases(configRoot);
+        default: {
+            const unhandled = root;
+            return unhandled;
+        }
+    }
+}
+function configurationSetBases(configRoot) {
+    if (configRoot === undefined)
+        throw new Error("a user-settings path rule reached the compiler without a configuration root — the admission judgement refuses it first (home_unresolvable); refusing rather than anchoring it at the task root");
+    return { root: configRoot };
+}
+function allowMemberOf(entry, configRoot) {
+    const root = ruleRootOf(entry, "allow");
+    switch (root) {
+        case "task":
+            return ruleTextOf(entry);
+        case "configuration":
+            return { rule: ruleTextOf(entry), pathBases: configurationSetBases(configRoot) };
         default: {
             const unhandled = root;
             return unhandled;
@@ -503,7 +523,7 @@ export function applyTaskSettings(base, settings, bases) {
         next = tightenGoverned(next, { ...(toolPolicy !== undefined ? { toolPolicy } : {}), ...seatSpec });
     const allow = settings.permissions?.allow;
     if (allow !== undefined)
-        next = { ...next, allowedTools: allow };
+        next = { ...next, allowedTools: allow.map((entry) => allowMemberOf(entry, bases?.configRoot)) };
     if (settings.outputStyle) {
         const appended = next.appendSystemPrompt ? `${next.appendSystemPrompt}\n\n${settings.outputStyle}` : settings.outputStyle;
         next = { ...next, appendSystemPrompt: appended };