dsh-kingdom 2.0.0 → 3.1.0

package/lib/types/core/delivery-change.d.ts

@@ -0,0 +1,381 @@
+import type { EventRow, KingdomStore } from './db.js';
+import { CHANGE_EVIDENCE_LABEL, CHANGE_EVIDENCE_NOTE } from './delivery-ack.js';
+export { CHANGE_EVIDENCE_LABEL, CHANGE_EVIDENCE_NOTE };
+export declare const DELIVERY_CHANGE_SNAPSHOT_EVENT_TYPE = "DELIVERY_CHANGE_SNAPSHOT";
+export declare const DELIVERY_CHANGE_MANIFEST_VERSION = "KingdomDeliveryChangeManifest/v1";
+export declare const DELIVERY_CHANGE_SNAPSHOT_VERSION = "KingdomDeliveryWorkspaceSnapshot/v1";
+export declare const CHANGE_EVIDENCE_DRIFT = "\u8BC1\u636E\u6B63\u6587\u7F3A\u5931\u6216\u54C8\u5E0C\u6F02\u79FB\uFF0C\u4E0D\u80FD\u4F5C\u4E3A\u53EF\u4FE1\u6539\u52A8\u5B9A\u4F4D\u3002";
+/** 采集与分析的有界上限；任何一项被触发都会如实反映为部分覆盖。 */
+export interface DeliveryChangeBounds {
+    maxFiles: number;
+    maxFileBytes: number;
+    /**
+     * 单个文件的**完整内容 hash**上限；超过即无法完整比较，只能如实记 `UNKNOWN`，
+     * 不得用「真实大小 + 有界首段」的前缀摘要冒充完整内容 hash。
+     */
+    maxHashBytes: number;
+    /** 单次采集允许读取的总字节数；超出后不再读取，未比较的文件必须如实计入部分覆盖。 */
+    maxReadBytes: number;
+    maxStoredBytes: number;
+    maxDiffLines: number;
+    maxEntries: number;
+    /** Git 候选枚举的字节上限；超出即视为无法安全枚举，如实报失败而不是截断成「无改动」。 */
+    maxCandidateBytes: number;
+    /** VCS 忽略样本的字节上限；只用于报告有多少内容被 ignore 规则排除，不读取其正文。 */
+    maxIgnoredBytes: number;
+}
+export declare const DEFAULT_DELIVERY_CHANGE_BOUNDS: DeliveryChangeBounds;
+export type DeliveryChangePhase = 'PRE' | 'POST';
+/**
+ * `UNKNOWN` 只用于「无法证明是否变化」的候选：内容过长/不可读/是符号链接导致
+ * 比较不可靠。它**不是**可由主管确认的改动条目，选择它会被拒绝。
+ */
+export type DeliveryChangeStatus = 'ADDED' | 'MODIFIED' | 'DELETED' | 'UNKNOWN';
+export type DeliveryChangeEvidenceKind = 'SUPERVISOR_CONFIRMED_BOUNDED_WINDOW';
+export interface DeliverySnapshotCoverage {
+    complete: boolean;
+    observedFiles: number;
+    retainedFiles: number;
+    /** 因上限被跳过的条目数下界；达到文件或读取预算上限后不再继续读取。 */
+    omittedByLimit: number;
+    /** 采集时无法读取、因此无法证明是否变化的候选数。 */
+    omittedUnreadable: number;
+    skippedSymlinks: number;
+    skippedOversize: number;
+    binaryFiles: number;
+    /** 检测到 PEM 私钥/证书标记、因而**不保留正文**的候选数（只保留摘要）。 */
+    sensitiveBodiesSkipped: number;
+    /**
+     * 被 VCS ignore 规则排除、因而从未成为候选的路径数（只计数与保留路径名样本）。
+     *
+     * 这是**有意**的范围限定：候选集合本身完整、只是不含被忽略内容，所以它只让
+     * `complete=false`，**不**使未忽略路径的「不在快照里 = 当时不存在」失效。
+     */
+    ignoredPaths: number;
+    /** 证据目录位于工作区内时被有意排除的路径数（避免把自身快照算成改动），同理不推断枚举被截断。 */
+    evidenceRootExcluded: number;
+    reasons: string[];
+    /** 被 VCS ignore 规则排除的路径名样本；只保留路径，不含正文。 */
+    ignoredSamples: string[];
+}
+export type DeliveryFileReadability = 'READABLE' | 'ABSENT' | 'UNREADABLE' | 'SYMLINK';
+export interface DeliveryWorkspaceFileObservation {
+    /** 工作区内采集用的规范化相对路径；仅用于本地读取与条目身份，不直接作为公开展示路径。 */
+    path: string;
+    /** 仓库相对路径；Owner 展示、主管候选与「查看改动」一律使用这一路径。 */
+    repoPath: string | null;
+    size: number;
+    binary: boolean;
+    symlink: boolean;
+    oversize: boolean;
+    /**
+     * 是否命中 PEM 私钥/证书标记、因而**不保留正文**。两侧任一为 `true` 时差异条目
+     * 都不展示正文片段：否则未命中一侧的历史正文会把另一侧的主体带进公开视图。
+     */
+    sensitive: boolean;
+    /** 是否把脱敏后的正文写入了内容寻址 blob（两侧都保留，便于展示增删片段）。 */
+    retained: boolean;
+    /** 完整内容摘要；无法完整读取（超限/部分读取）时为 null，绝不退化成前缀摘要。 */
+    rawHash: string | null;
+    storedHash: string | null;
+    /** 采集时刻该路径的 `git status --porcelain` 代码；无 VCS 时为 null。 */
+    vcs: string | null;
+    /** 本次采集对该路径的实际可读性判定；决定差异能否被证明。 */
+    readability: DeliveryFileReadability;
+}
+export interface DeliveryRepoIdentity {
+    vcs: 'GIT' | 'UNAVAILABLE';
+    /** 仓库身份的不可逆摘要，避免证据里出现本机绝对路径。 */
+    identity: string | null;
+    head: string | null;
+    scope: 'REPO_ROOT' | 'WORKSPACE_SUBDIR' | 'OUTSIDE_REPO' | 'UNKNOWN';
+    reason: string | null;
+}
+export interface DeliveryWorkspaceSnapshot {
+    version: typeof DELIVERY_CHANGE_SNAPSHOT_VERSION;
+    snapshotId: string;
+    phase: DeliveryChangePhase;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    workspaceKey: string;
+    executionId: string | null;
+    leaseId: string | null;
+    dispatchId: string | null;
+    repo: DeliveryRepoIdentity;
+    capturedAt: string;
+    files: DeliveryWorkspaceFileObservation[];
+    coverage: DeliverySnapshotCoverage;
+    /** 候选枚举本身的有界元数据（不含正文）：便于区分「无改动」与「没能枚举完整」。 */
+    candidateScope: {
+        kind: 'VCS_CANDIDATES';
+        candidateCount: number;
+        pathspec: string;
+        evidencePrefix: string | null;
+        evidenceRootExcluded: number;
+    };
+    /**
+     * 该时刻的候选集合是否**完整可信**：本快照里「没有该路径」是否可以当成「它当时不存在」。
+     *
+     * 只有下列条件同时成立才为 `true`：候选枚举未被文件/读取预算截断，也没有读不出来的候选。
+     *
+     * `.gitignore` 排除的内容与证据目录自身是**有意**待在候选集合之外的范围限定：候选
+     * 枚举本身是完整的，因此它们只如实记为部分覆盖（`coverage.reasons`），**不**推断
+     * 「未忽略路径的存在性不可证明」。把有意排除当成枚举截断会让真实新增无法确认。
+     */
+    enumerationComplete: boolean;
+    /**
+     * 被 ignore 规则排除的路径身份（工作区相对）；只含路径名，不含任何正文。
+     *
+     * 增删判定不只看「该路径在不在快照里」，还要看它是否出现在**另一时点**的这份身份
+     * 集合中：只改忽略规则时，内容未变的旧文件会离开或进入候选集合，那个缺项其实是被
+     * ignore，既不是窗口内新增也不是窗口内删除。
+     */
+    ignoredPathIdentities: string[];
+    /**
+     * 上述身份集合是否完整可信（枚举未被字节上限截断）。
+     *
+     * `false` 时不得把「路径不在集合里」当成「它当时未被忽略」：增删判定必须 fail-closed，
+     * 否则无法排除「另一个时点其实被 ignore」这一可能。
+     */
+    ignoredPathsComplete: boolean;
+}
+export interface DeliveryChangeHunk {
+    kind: 'ADDED' | 'REMOVED';
+    beforeLine: number | null;
+    afterLine: number | null;
+    text: string;
+}
+export interface DeliveryChangeEntry {
+    entryId: string;
+    /** 工作区相对路径；本地读取与身份用，不作为公开展示路径。 */
+    path: string;
+    /** 仓库相对路径（Owner 详情、主管候选与工作台固定展示这一条）。 */
+    repoPath: string;
+    status: DeliveryChangeStatus;
+    reasonCode: string;
+    labels: string[];
+    note: string;
+    binary: boolean;
+    bodyRetained: boolean;
+    beforeHash: string | null;
+    afterHash: string | null;
+    /** 基线正文未保留（预算/二进制/超限）时无法展示删除片段。 */
+    baselineBodyUnavailable: boolean;
+    hunks: DeliveryChangeHunk[];
+}
+export interface DeliveryChangeManifest {
+    version: typeof DELIVERY_CHANGE_MANIFEST_VERSION;
+    evidenceId: string;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    workspaceKey: string;
+    repo: DeliveryRepoIdentity;
+    executionId: string | null;
+    leaseId: string | null;
+    dispatchId: string | null;
+    pre: {
+        snapshotId: string;
+        capturedAt: string;
+        coverage: DeliverySnapshotCoverage;
+    };
+    post: {
+        snapshotId: string;
+        capturedAt: string;
+        coverage: DeliverySnapshotCoverage;
+    };
+    entries: DeliveryChangeEntry[];
+    coverage: {
+        complete: boolean;
+        reasons: string[];
+        entryCount: number;
+        omitted: number;
+    };
+    note: string;
+    createdAt: string;
+}
+/** 主管 ACCEPT 时显式选中的改动引用（写入 TASK_ACCEPTED payload）。 */
+export interface DeliveryChangeEvidenceRef {
+    kind: DeliveryChangeEvidenceKind;
+    evidenceId: string;
+    attemptNo: number;
+    entryIds: string[];
+    selectionDigest: string;
+    entryCount: number;
+    selectedCount: number;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    repoHead: string | null;
+    note: string;
+}
+export interface DeliveryEvidencePaths {
+    root: string;
+    snapshots: string;
+    blobs: string;
+    manifests: string;
+}
+/**
+ * 交付改动证据的专用本机持久目录：<dshHome>/kingdom/delivery-evidence。
+ *
+ * 只保存有界、脱敏、内容寻址的快照与差异；不接触 kingdom.db 本身。
+ * `DSH_KINGDOM_EVIDENCE_ROOT` 只用于把测试指向一次性临时目录。
+ */
+export declare function deliveryEvidenceRoot(): string;
+export declare function deliveryEvidencePaths(evidenceRoot?: string): DeliveryEvidencePaths;
+export declare function readChangeBlob(evidenceRoot: string | undefined, storedHash: string): string | null;
+export type CaptureSnapshotResult = {
+    ok: true;
+    snapshot: DeliveryWorkspaceSnapshot;
+    snapshotFile: string;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+export interface CaptureSnapshotInput {
+    workspacePath: string;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    phase: DeliveryChangePhase;
+    executionId?: string | null;
+    leaseId?: string | null;
+    dispatchId?: string | null;
+    evidenceRoot?: string;
+    bounds?: Partial<DeliveryChangeBounds>;
+    now?: string;
+}
+/**
+ * 冻结一份有界工作区快照。**永不抛出**：采集失败只返回 `ok:false`，
+ * 调用方据此不产生任何改动链接，而不是把失败伪装成空差异。
+ *
+ * 候选路径全部来自 Git（见 {@link enumerateCandidates}）：没有可用的 Git 基准、
+ * 枚举失败或输出超限时直接返回失败，绝不退化成「扫描任意工作区正文」。
+ */
+export declare function captureWorkspaceSnapshot(input: CaptureSnapshotInput): CaptureSnapshotResult;
+export declare function readWorkspaceSnapshot(evidenceRoot: string | undefined, snapshotId: string): DeliveryWorkspaceSnapshot | null;
+export declare function deliveryChangeEvidenceId(manifest: DeliveryChangeManifest): string;
+export type BuildChangeManifestResult = {
+    ok: true;
+    manifest: DeliveryChangeManifest;
+    file: string;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 采集执行前的有界基线；失败返回 null（调用方不得伪造空差异）。 */
+export declare function capturePreChangeSnapshot(input: Omit<CaptureSnapshotInput, 'phase'>): DeliveryWorkspaceSnapshot | null;
+export interface CompleteChangeManifestInput {
+    workspacePath: string;
+    pre: DeliveryWorkspaceSnapshot;
+    taskId: string;
+    attemptNo: number;
+    territoryId: string;
+    executionId?: string | null;
+    leaseId?: string | null;
+    dispatchId?: string | null;
+    evidenceRoot?: string;
+    bounds?: Partial<DeliveryChangeBounds>;
+}
+/**
+ * terminal / WorkerResult 之前采集 POST 并生成差异 manifest。
+ *
+ * 采集或写入任一步失败都返回 null：宁可没有改动定位，也不产生不可信的链接。
+ */
+export declare function capturePostAndBuildChangeManifest(input: CompleteChangeManifestInput): DeliveryChangeManifest | null;
+export interface BuildChangeManifestInput {
+    evidenceRoot?: string;
+    pre: DeliveryWorkspaceSnapshot;
+    post: DeliveryWorkspaceSnapshot;
+    bounds?: Partial<DeliveryChangeBounds>;
+    resultRef?: string | null;
+    now?: string;
+}
+/** 由 PRE/POST 两份快照生成有界、脱敏的差异 manifest，并原子写入内容寻址文件。 */
+export declare function buildDeliveryChangeManifest(input: BuildChangeManifestInput): BuildChangeManifestResult;
+/** 有界行级差异：裁掉公共前后缀后，把中段如实标成 REMOVED/ADDED 片段。 */
+export declare function diffLines(before: string, after: string, maxLines: number): DeliveryChangeHunk[];
+export type VerifyChangeManifestResult = {
+    ok: true;
+    manifest: DeliveryChangeManifest;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 读回并按内容寻址重验 manifest 与保留正文的 hash；漂移即不可用。 */
+export declare function verifyChangeManifest(evidenceRoot: string | undefined, evidenceId: string): VerifyChangeManifestResult;
+/** 读取由主管 ACCEPT 绑定在该 Task 上的改动证据引用。 */
+export declare function readAcceptedChangeEvidence(review: EventRow | null): DeliveryChangeEvidenceRef | null;
+export declare function selectionDigest(entryIds: readonly string[]): string;
+/**
+ * 校验主管显式选择：evidence 必须存在且 hash 一致，选中的 entry 必须真实存在。
+ * 任一失败都返回错误，调用方必须拒绝并零写入。
+ */
+export declare function validateChangeSelection(evidenceRoot: string | undefined, manifest: DeliveryChangeManifest, entryIds: readonly string[], expected: {
+    taskId: string;
+    attemptNo: number;
+}): {
+    ok: true;
+    ref: DeliveryChangeEvidenceRef;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 事件载荷：只含 task/attempt/result、manifest/hash 与有界元数据，不含仓库正文。 */
+export declare function changeSnapshotEventPayload(manifest: DeliveryChangeManifest, resultRef: string | null): Record<string, unknown>;
+export declare function changeSnapshotEventId(kingdomId: string, taskId: string, attemptNo: number, executionRef: string | null): string;
+/** Territory canonical workspace 的不可逆摘要，用于把快照绑定到具体领地工作区。 */
+export declare function workspaceKeyOf(workspacePath: string): string | null;
+export interface ChangeSnapshotEventRef {
+    event: EventRow;
+    evidenceId: string;
+    attemptNo: number;
+    resultId: string | null;
+    executionId: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+}
+/** 精确读取某 Task/attempt 的改动快照事件（不走有界 GUI 投影）。 */
+export declare function readChangeSnapshotEvent(store: KingdomStore, kingdomId: string, taskId: string, attemptNo: number): ChangeSnapshotEventRef | null;
+/** 主管候选清单用的有界条目视图（只读，不写任何事实）；展示路径是仓库相对路径。 */
+export declare function listChangeEntries(manifest: DeliveryChangeManifest, limit?: number): {
+    entryId: string;
+    repoPath: string;
+    status: string;
+    note: string;
+}[];
+/** 读回一条已确认改动条目的有界视图：只按 entry id 取，不接受任意路径。 */
+export declare function readChangeEntry(evidenceRoot: string | undefined, ref: DeliveryChangeEvidenceRef, entryId: string): {
+    ok: true;
+    entry: DeliveryChangeEntry;
+    manifest: DeliveryChangeManifest;
+} | {
+    ok: false;
+    code: string;
+    reason: string;
+};
+/** 交付条目派生用的已解析证据形状（与 `delivery-ack.ts` 的结构一致）。 */
+export interface ResolvedChangeEvidence {
+    evidenceId: string;
+    attemptNo: number;
+    repoHead: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    note: string;
+    /** 条目展示路径一律是仓库相对路径。 */
+    entries: {
+        entryId: string;
+        repoPath: string;
+        status: string;
+        note: string;
+    }[];
+}
+/**
+ * 把已确认的改动引用解析成可投影条目。任何 hash 漂移或正文缺失都返回 null，
+ * 调用方据此显示「不可定位」，而不是继续用可能被替换的正文。
+ */
+export declare function resolveChangeEvidenceForDelivery(evidenceRoot: string | undefined, ref: DeliveryChangeEvidenceRef): ResolvedChangeEvidence | null;

package/lib/types/core/owner-window.d.ts

@@ -3,7 +3,8 @@ import { type ExecutionProfileV1 } from './binding.js';
 import { type OwnerControlCapability } from './owner-control.js';
 import { type BudgetPolicyParameters } from './budget.js';
 import { type PlanAdoptionParameters, type CollaborationPlanView } from './collaboration.js';
-export declare const OWNER_MUTATION_ACTIONS: readonly ["init", "territory.create", "territory.update", "territory.supervisor", "role.bind", "role.session", "ceiling", "execution-profile", "budget.policy", "plan.adopt"];
+import { type DeliveryAcceptanceEvidenceKind, type DeliveryItemVersionState, type DeliveryReplyState } from './delivery-ack.js';
+export declare const OWNER_MUTATION_ACTIONS: readonly ["init", "territory.create", "territory.update", "territory.supervisor", "role.bind", "role.session", "ceiling", "execution-profile", "budget.policy", "plan.adopt", "delivery.item.ack", "delivery.item.question"];
 export type OwnerMutationAction = typeof OWNER_MUTATION_ACTIONS[number];
 export type OwnerManagedRole = 'CHANCELLOR' | 'SUPERVISOR' | 'WORKER';
 export interface OwnerDecisionScope {
@@ -60,6 +61,148 @@ export interface OwnerRuntimeSessionChoice {
     id: string;
     label: string;
 }
+/** 交付清单条目：只有已被主管 ACCEPT 确认的交付才会出现。 */
+export interface OwnerDeliveryItemChoice {
+    taskId: string;
+    taskTitle: string;
+    deliveryId: string;
+    attemptNo: number;
+    resultId: string;
+    itemId: string;
+    contentHash: string;
+    layer: string;
+    label: string;
+    detail: string;
+    changeKind: string;
+    changeNote: string;
+    acknowledgementState: 'ACKNOWLEDGED' | 'PENDING' | 'PENDING_REVISION';
+    acknowledgedAt: string | null;
+    /**
+     * 本次确认交付实际依据的接受证据强度。`LEGACY_ATTEMPT_ONLY` 时
+     * `acceptanceEvidenceNote` 必须原样展示给 Owner（历史接受证据较弱），
+     * 且不得把它当作 exact result-bound。
+     */
+    acceptanceEvidenceKind: DeliveryAcceptanceEvidenceKind;
+    acceptanceEvidenceExact: boolean;
+    acceptanceEvidenceNote: string | null;
+    /**
+     * 该条目已有的 Owner 提问元数据（不含正文）。正文只经
+     * {@link OwnerDecisionController.readDeliveryQuestions} 在有效窗口内按精确条目返回。
+     */
+    questions: OwnerDeliveryItemQuestions | null;
+}
+/** 条目提问的**元数据**：不含问题或回复正文。 */
+export interface OwnerDeliveryItemQuestions {
+    threadId: string;
+    totalCount: number;
+    /** 主管尚未回复的问题数；未被实际读取前只算「待领取」。 */
+    pendingCount: number;
+    answeredCount: number;
+    /** 属于旧内容版本、仅留历史的问题数。 */
+    historyCount: number;
+    lastAskedAt: string | null;
+    lastRepliedAt: string | null;
+    /** 最近一条问题的接收主管是否仍可回复；不可达时界面必须照实说明。 */
+    latestReplyState: DeliveryReplyState | null;
+}
+/**
+ * Owner 只读问答历史入口的一条精确条目（不含问题或回复正文）。
+ *
+ * 与 `deliveryItems` 分开：它只来自既有提问事实，因此包含已经离开当前交付目录、
+ * 目前无法重验的旧问答。它只供只读回看，**绝不**作为新提问目标；新提问仍须落在
+ * 当前已确认交付目录内并逐条精确重验。
+ */
+export interface OwnerDeliveryQuestionHistoryChoice {
+    taskId: string;
+    taskTitle: string;
+    itemId: string;
+    itemLabel: string;
+    lastAskedAt: string;
+    questionCount: number;
+    /** 已验证当前版本且尚无回复的条数；历史版与无法重验的都不计入。 */
+    pendingCount: number;
+    answeredCount: number;
+    historyCount: number;
+    unverifiableCount: number;
+    latestItemVersion: DeliveryItemVersionState;
+    currentContentHash: string | null;
+}
+/**
+ * Owner 只读的条目问答线程。
+ *
+ * 与「查看改动」同款边界：只经有效 Owner 窗口、精确条目引用与本次动作授权返回，
+ * **读取不写任何事实**、不自动知悉、也不替主管回复。
+ */
+export interface OwnerDeliveryQuestionEntry {
+    questionId: string;
+    questionText: string;
+    askedAt: string;
+    ownerId: string;
+    /** 接受该交付的主管 binding；首版唯一合法接收者。 */
+    reviewerBindingId: string;
+    replyState: DeliveryReplyState;
+    replyStateNote: string;
+    /**
+     * 该问题相对当前交付目录的版本关系：已验证当前、可确认的旧版本，或无法重验。
+     * 后两者仍可读、仍保留原文与回复，但**不计当前待办**，界面也不得据此声称
+     * 「当前可回复」。
+     */
+    itemVersion: DeliveryItemVersionState;
+    /** 当前读取时该条目重新派生出的内容版本；无法派生时为 null。 */
+    currentItemContentHash: string | null;
+    reply: {
+        replyText: string;
+        repliedAt: string;
+        responderBindingId: string;
+    } | null;
+}
+export interface OwnerDeliveryQuestionView {
+    deliveryId: string;
+    taskId: string;
+    taskTitle: string;
+    itemId: string;
+    itemLabel: string;
+    /** 本次读取时该条目的当前内容版本；无法在当前交付目录中重验时为 null。 */
+    contentHash: string | null;
+    questions: OwnerDeliveryQuestionEntry[];
+    answeredCount: number;
+    /** 已验证当前版本且尚无回复的条数；历史版与无法重验的未答问题都不计入。 */
+    pendingCount: number;
+    historyCount: number;
+    /** 当前交付目录无法重验该条目版本、因此不声称任何版本关系的条数。 */
+    unverifiableCount: number;
+    note: string;
+}
+/**
+ * Owner 只读的已确认改动详情。
+ *
+ * 这是「主管确认的改动证据」的可读视图：只经有效 Owner 窗口、精确
+ * task/evidence/entry id 与 scope 返回，**查看不写入任何事实**，也不自动知悉。
+ */
+export interface OwnerDeliveryChangeView {
+    kind: 'SUPERVISOR_CONFIRMED_BOUNDED_WINDOW';
+    label: string;
+    evidenceId: string;
+    entryId: string;
+    taskId: string;
+    taskTitle: string;
+    attemptNo: number;
+    status: string;
+    repoPath: string;
+    revision: string;
+    repoVcs: string;
+    repoHead: string | null;
+    coverageComplete: boolean;
+    coverageReasons: string[];
+    labels: string[];
+    note: string;
+    hunks: {
+        kind: string;
+        beforeLine: number | null;
+        afterLine: number | null;
+        text: string;
+    }[];
+}
 export interface OwnerDecisionControllerOptions {
     now?: () => number;
     validationTimeoutMs?: number;
@@ -83,6 +226,16 @@ export interface OwnerOperationCatalog {
     }[];
     runtimeSessions: OwnerRuntimeSessionChoice[];
     workspaceRoots: string[];
+    /**
+     * 本次授权范围内的已确认交付条目；逐条知悉与逐条提问共用同一份目录。
+     * 只要窗口授权了其中任一动作就返回；读取权限仍由各自动作单独把关。
+     */
+    deliveryItems?: OwnerDeliveryItemChoice[];
+    /**
+     * 本次授权范围内**已有提问记录**的精确条目只读入口（含已离开当前目录的旧问答）。
+     * 只在窗口授权 `delivery.item.question` 时返回，供只读回看；不是新提问目标来源。
+     */
+    deliveryQuestionHistory?: OwnerDeliveryQuestionHistoryChoice[];
 }
 export type OwnerOperationInput = {
     action: 'init';
@@ -140,6 +293,27 @@ export type OwnerOperationInput = {
 } | {
     action: 'plan.adopt';
     parameters: PlanAdoptionParameters;
+} | {
+    action: 'delivery.item.ack';
+    parameters: {
+        task_id: string;
+        delivery_id: string;
+        item_id: string;
+        content_hash: string;
+        attempt_no: number;
+        result_id: string;
+    };
+} | {
+    action: 'delivery.item.question';
+    parameters: {
+        task_id: string;
+        delivery_id: string;
+        item_id: string;
+        content_hash: string;
+        attempt_no: number;
+        result_id: string;
+        question_text: string;
+    };
 };
 export interface OwnerOperationPreview {
     prepareId: string;
@@ -170,7 +344,7 @@ export interface OwnerOperationReceipt {
     inputHash: string;
     status: 'APPLIED';
     target: {
-        type: 'kingdom' | 'territory' | 'binding' | 'collaboration-plan';
+        type: 'kingdom' | 'territory' | 'binding' | 'collaboration-plan' | 'delivery';
         id: string;
     };
     receiptSeq: number;
@@ -196,6 +370,65 @@ export declare class OwnerDecisionController {
     };
     inspect(handle: OwnerDecisionHandle): OwnerDecisionView | null;
     catalog(handle: OwnerDecisionHandle): Promise<OwnerOperationCatalog>;
+    /**
+     * 本次授权范围内的**已有提问记录**条目（只读历史入口）。
+     *
+     * 只读且不依赖有界交付目录：它按权威提问事实列出精确 task/item，再逐条用
+     * `deliveryScopeAllows` 过滤，因此不含跨领地条目；不在当前目录、当前无法重验的
+     * 旧问答也能在这里被发现。它不返回任何正文，也**不**进入新提问 prepare 的来源目录。
+     */
+    private deliveryQuestionHistory;
+    /**
+     * 交付知悉的授权范围判据。
+     *
+     * catalog 与 prepare/commit 必须共用同一判据：否则会出现「清单可见、
+     * 提交被拒」或「清单不可见、提交却可行」。`kingdomWide` 是 Owner 的最高
+     * 授权级别；其余情况要求任务所在领地在 `territoryIds` 内，或该领地由
+     * 授权 `bindingIds` 中的主管主理且本次授权声明了 SUPERVISOR 角色。
+     */
+    private deliveryScopeAllows;
+    /**
+     * 本次授权范围内的已确认交付条目。只有同一 Task/attempt 主管 ACCEPT 的交付才出现，
+     * Worker Claim 永远不会进入该清单。
+     */
+    private deliveryItems;
+    /**
+     * 只读返回一条已确认交付条目的完整问答线程。
+     *
+     * 有效性要求与 `readDeliveryChange` 同款：窗口 ACTIVE、本次授权包含
+     * `delivery.item.question`、任务在授权范围内、该 task 确实存在写给它的问题记录。
+     * 版本关系按该精确 task/item **独立重验**（不受有界展示目录截断影响）：命中当前
+     * 派生版本即已验证当前版，命中的是旧版本即历史版；条目已无法从当前 ACCEPT/证据
+     * 重验（例如 CHANGE 证据丢失）时仍可按精确 itemId 读回，但整条标为无法重验，
+     * 不冒充当前版、也不可回复。任一不成立都失败，且不写任何事实、不自动知悉。
+     */
+    readDeliveryQuestions(handle: OwnerDecisionHandle, input: {
+        taskId: string;
+        itemId: string;
+    }): OwnerDeliveryQuestionView;
+    /**
+     * 已由主管在 ACCEPT 中显式选择、且本地 hash 重验通过的改动证据。
+     * 缺失、漂移或未确认时返回 null：调用方显示「不可定位」，不退回执行者自述。
+     */
+    private changeEvidenceFor;
+    private acceptedChangeRef;
+    /**
+     * 只读返回一条已确认改动条目的有界详情。
+     *
+     * 有效性要求：窗口 ACTIVE、**本次授权动作包含 `delivery.item.ack`**、任务在本次
+     * 授权范围内、该 task 确实存在一条主管 ACCEPT 绑定的改动证据、evidence id 与
+     * entry id 精确匹配、该条目仍需出现在当前有效交付目录中，且本地 hash 重验通过。
+     * 任一不成立都失败，且不写任何事实、不产生知悉。
+     *
+     * 只检查 ACTIVE + Territory scope 是不够的：同一领地的另一个管理窗口若没有该
+     * 动作授权，就不能凭 id 读取差异正文。这里与 `catalog` 使用同一动作判据，
+     * 不默认放行（也不新增只读动作）。
+     */
+    readDeliveryChange(handle: OwnerDecisionHandle, input: {
+        taskId: string;
+        evidenceId: string;
+        entryId: string;
+    }): OwnerDeliveryChangeView;
     prepare(handle: OwnerDecisionHandle, raw: OwnerOperationInput, options?: {
         signal?: AbortSignal;
     }): Promise<OwnerOperationPreview>;

package/lib/types/core/task-service.d.ts

@@ -106,12 +106,34 @@ export interface StartTaskInput {
  * - executor 客观失败 → **RUNNING → FAILED** + `WORKER_EXECUTION_FAILED`，且不落 Claim。
  */
 export declare function startTask(store: KingdomStore, executor: WorkerExecutor, ctx: CommandContext, input: StartTaskInput): Promise<CommandResultView>;
+/**
+ * 主管只读候选清单：列出本 Task 当前 attempt 的有界改动条目。
+ *
+ * 这是主管「查看候选并显式选择」的入口；它只读、不写任何事实，也要求
+ * 真实 session-bound 主管。没有快照时如实说明，不伪造候选。
+ */
+export declare function describeTaskChangeCandidates(store: KingdomStore, ctx: CommandContext, taskId: string): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    code: KingdomErrorCode;
+    message: string;
+};
 export interface ReviewTaskInput {
     taskId: string;
     decision: string;
     reason?: string;
     /** HANDOFF 专用：目标 Worker binding id。 */
     to_binding_id?: string;
+    /**
+     * ACCEPT 专用：主管显式选择属于本次交付的改动引用。
+     *
+     * 两者必须同时给出；只给 evidence id 或只给空选择都视为非法，普通 ACCEPT
+     * 不会自动确认全部 diff。确认入口额外要求真实 session-bound 主管会话。
+     */
+    change_evidence_id?: string;
+    change_entry_ids?: string[];
 }
 /**
  * Supervisor 审查 Worker Claim，把 Claim 转成组织事实（v0.7.0：scope + HANDOFF + Ledger 关闭）。