dsh-kingdom 0.8.0 → 2.0.0

package/lib/types/gui/contract.d.ts

@@ -45,13 +45,14 @@ export type ActorState = (typeof ACTOR_STATES)[number];
  */
 export type ActorActivity = 'plan' | 'read' | 'assign' | 'review' | 'rework' | 'accept' | 'execute' | null;
 /** 命令返回的稳定错误码。GUI 据此决定提示与可用按钮，不解析中文文案。 */
-export type KingdomErrorCode = 'KINGDOM_NOT_INITIALIZED' | 'ROLE_BINDING_MISSING' | 'UNAUTHORIZED_PRINCIPAL' | 'SESSION_AUTH_REQUIRED' | 'TERRITORY_MISSING' | 'TERRITORY_AMBIGUOUS' | 'TERRITORY_NOT_IN_KINGDOM' | 'TASK_NOT_FOUND' | 'TASK_NOT_IN_KINGDOM' | 'ILLEGAL_TASK_STATE' | 'INVALID_INPUT' | 'INVALID_DECISION' | 'REASON_REQUIRED' | 'WORKER_BINDING_INVALID' | 'WORKER_AMBIGUOUS' | 'TERRITORY_SUPERVISOR_MISSING' | 'TASK_OUT_OF_SCOPE' | 'EXECUTOR_UNAVAILABLE' | 'WORKER_EXECUTION_FAILED' | 'EXECUTION_NOT_FOUND' | 'ILLEGAL_EXECUTION_STATE';
+export type KingdomErrorCode = 'KINGDOM_NOT_INITIALIZED' | 'ROLE_BINDING_MISSING' | 'UNAUTHORIZED_PRINCIPAL' | 'SESSION_AUTH_REQUIRED' | 'TERRITORY_MISSING' | 'TERRITORY_AMBIGUOUS' | 'TERRITORY_NOT_IN_KINGDOM' | 'TASK_NOT_FOUND' | 'TASK_NOT_IN_KINGDOM' | 'ILLEGAL_TASK_STATE' | 'INVALID_INPUT' | 'INVALID_DECISION' | 'REASON_REQUIRED' | 'WORKER_BINDING_INVALID' | 'WORKER_AMBIGUOUS' | 'TERRITORY_SUPERVISOR_MISSING' | 'TASK_OUT_OF_SCOPE' | 'EXECUTOR_UNAVAILABLE' | 'WORKER_EXECUTION_FAILED' | 'CLAIM_INTEGRITY_BLOCKED' | 'EXECUTION_NOT_FOUND' | 'ILLEGAL_EXECUTION_STATE' | 'RECOVERY_REQUIRED';
 /**
  * v0.5.2（M1-B/P0-B）：GUI 写命令守卫。
  *
  * GUI 网关没有可信 DSH Principal（HTTP payload 的 session_id 一律不再被信任），
- * 因此 `session-bound` 模式下所有写命令 fail-closed——宁可少一个按钮能用，
- * 也不能让 GUI 伪造治理身份。`declarative` 是本地可信演示模式，保持可用。
+ * R02 Owner Control ruling：GUI/HTTP 没有可信 direct Owner capability，
+ * 因此所有写命令都 fail-closed；declarative 仅保留为历史 fixture 语义，
+ * 不能解锁产品写入。
  */
 export declare function guiWriteGuard(authMode: string): {
     allowed: true;
@@ -60,7 +61,345 @@ export declare function guiWriteGuard(authMode: string): {
     code: 'SESSION_AUTH_REQUIRED';
 };
 /** GUI 可以呈现为按钮的下一步动作。 */
-export type AllowedAction = 'assign' | 'start' | 'review:accept' | 'review:rework' | 'review:fail' | 'execution:pause' | 'execution:resume' | 'execution:abort';
+export type AllowedAction = 'assign' | 'start' | 'reconcile' | 'review:accept' | 'review:rework' | 'review:fail' | 'review:handoff' | 'execution:pause' | 'execution:resume' | 'execution:abort';
+/** v0.9 S1：Projection 的可公开、可追溯来源引用。不得放入 raw payload/session/path。 */
+export type ProjectionSourceType = 'table-row' | 'event' | 'runtime-evidence' | 'derived-rule';
+export interface SourceRef {
+    sourceType: ProjectionSourceType;
+    entityType: string;
+    entityId: string | null;
+    eventSeq?: number;
+    ruleCode?: string;
+}
+export interface EntityRef {
+    type: string;
+    id: string;
+}
+export type ProjectionSourceKind = 'GOVERNANCE_FACT' | 'RUNTIME_OBSERVATION';
+export interface AuthoritativeState {
+    sourceKind: ProjectionSourceKind;
+    value: string;
+    sourceRefs: SourceRef[];
+}
+export interface AttentionReason {
+    code: string;
+    sourceRefs: SourceRef[];
+}
+export interface ActionAvailability {
+    action: AllowedAction | string;
+    lifecycleAllowed: boolean;
+    executable: boolean;
+    disabledReason: AttentionReason | null;
+    sourceRefs: SourceRef[];
+}
+export type ProjectionItemKind = 'GOVERNANCE_FACT' | 'RUNTIME_OBSERVATION' | 'WORKER_CLAIM' | 'DERIVED_EXPLANATION';
+export type ProjectionTerminality = 'NON_TERMINAL' | 'TERMINAL' | 'UNKNOWN';
+export interface TimelineItem {
+    id: string;
+    kind: ProjectionItemKind;
+    occurredAt: string | null;
+    entityRef: EntityRef | null;
+    authoritativeState: AuthoritativeState | null;
+    sourceRefs: SourceRef[];
+    allowedActions: ActionAvailability[] | null;
+    attentionReason: AttentionReason | null;
+    terminality: ProjectionTerminality;
+    summary: string;
+    requiresOwnerAction: boolean;
+    rawEvidenceAvailable: boolean;
+}
+export interface AttentionItem {
+    id: string;
+    severity: 'ATTENTION' | 'CRITICAL' | 'UNKNOWN';
+    entityRef: EntityRef | null;
+    reason: AttentionReason;
+    summary: string;
+    sourceRefs: SourceRef[];
+}
+export interface ProjectionEnvelope<T> {
+    revision: number;
+    refreshedAt: string;
+    entityRef: EntityRef | null;
+    authoritativeState: AuthoritativeState | null;
+    sourceRefs: SourceRef[];
+    allowedActions: ActionAvailability[] | null;
+    attentionReason: AttentionReason | null;
+    data: T;
+}
+export interface OverviewProjectionData {
+    health: 'OK' | 'ATTENTION' | 'CRITICAL' | 'UNKNOWN';
+    /** Optional business-facing health wording supplied by the projection/fixture. */
+    healthTitle?: string | null;
+    healthLabel?: string | null;
+    healthMetrics?: {
+        blockedWorkers: number;
+        frozenTerritories: number;
+        attentionCount: number;
+    } | null;
+    taskCount: number;
+    activeExecutionCount: number;
+    statusCounts: Record<string, number>;
+    ownerActions: ActionAvailability[];
+}
+/** v1.0：组织页使用的有界角色摘要；不包含 session/model/meta/private path。 */
+export interface OrganizationRoleSummary {
+    bindingRef: EntityRef;
+    roleType: string;
+    roleName: string;
+    /**
+     * Canonical organization scope for this binding when one exact territory is
+     * knowable. `null` is intentional for a worker with no current affinity or
+     * with conflicting territory evidence; the GUI must keep that actor visible
+     * in an explicit unassigned/unknown area.
+     */
+    territoryRef: EntityRef | null;
+    status: AuthoritativeState;
+    sessionBound: boolean;
+    sourceRefs: SourceRef[];
+}
+/** v1.0：组织页使用的有界 Territory 摘要；workspace path 永不进入 Projection。 */
+export interface OrganizationTerritorySummary {
+    territoryRef: EntityRef;
+    name: string;
+    status: AuthoritativeState;
+    supervisorBindingRef: EntityRef | null;
+    taskCount: number;
+    sourceRefs: SourceRef[];
+}
+export interface OrganizationProjectionData {
+    kingdomName: string | null;
+    bindingCount: number;
+    territoryCount: number;
+    roles: OrganizationRoleSummary[];
+    territories: OrganizationTerritorySummary[];
+    rolesTruncated: boolean;
+    territoriesTruncated: boolean;
+}
+/** v1.0：Execution 导航使用的运行事实摘要；Claim 与治理 Fact 不在此混写。 */
+export interface ExecutionProjectionSummary {
+    executionId: string;
+    taskId: string;
+    executionRef: EntityRef;
+    taskRef: EntityRef;
+    workerBindingRef: EntityRef | null;
+    attemptNo: number;
+    state: string;
+    authoritativeState: AuthoritativeState;
+    executionContract: string;
+    terminality: ProjectionTerminality;
+    pausePending: boolean;
+    startedAt: string | null;
+    endedAt: string | null;
+    actionAvailability: ActionAvailability[];
+    attentionReason: AttentionReason | null;
+    sourceRefs: SourceRef[];
+}
+export interface ExecutionProjectionData {
+    totalExecutionCount: number;
+    items: ExecutionProjectionSummary[];
+    truncated: boolean;
+}
+export interface TaskProjectionData {
+    taskRef: EntityRef;
+    status: AuthoritativeState;
+    claim: {
+        outcome: string;
+        sourceRefs: SourceRef[];
+    } | null;
+    execution: {
+        state: string;
+        executionContract: string;
+        terminality: ProjectionTerminality;
+        sourceRefs: SourceRef[];
+    } | null;
+    actionAvailability: ActionAvailability[];
+}
+/** v1.2：工作台只是现有事实的有界投影，不创建待办/验收状态库。 */
+export interface WorkbenchQueue<T> {
+    totalCount: number;
+    items: T[];
+    truncated: boolean;
+}
+export interface WorkbenchActionItem {
+    id: string;
+    kind: string;
+    taskId: string | null;
+    territoryId: string | null;
+    title: string;
+    summary: string;
+    responsibility: 'OWNER' | 'CHANCELLOR' | 'SUPERVISOR' | 'UNDETERMINED';
+    responsibleBindingId: string | null;
+    /** 复用原有服务端许可；责任分类本身不授予调用权限。 */
+    actionAvailability: ActionAvailability[];
+    sourceRefs: SourceRef[];
+}
+export interface WorkbenchDeliveryItem {
+    taskId: string;
+    title: string;
+    status: string;
+    claim: ClaimView | null;
+    supervisorAccepted: boolean;
+    supervisorDecision: SupervisorDecisionView | null;
+    /** 当前没有人类验收事实；DONE 也不能填为人类已验收。 */
+    humanAcceptance: 'NOT_RECORDED';
+    updatedAt: string;
+    sourceRefs: SourceRef[];
+}
+export interface WorkbenchRoleItem {
+    bindingId: string;
+    roleType: string;
+    roleName: string;
+    sessionBound: boolean;
+    taskCount: number;
+    taskIds: string[];
+    taskIdsTruncated: boolean;
+    activeExecutionCount: number;
+    reviewTaskCount: number;
+    recoveringTaskCount: number;
+    sourceRefs: SourceRef[];
+}
+export interface WorkbenchUsageSummary {
+    scope: 'WORKER_DISPATCH_ONLY';
+    totalDispatches: number;
+    completeDispatches: number;
+    partialDispatches: number;
+    unavailableDispatches: number;
+    /** 实际执行中没有对应 Dispatch 的次数，可能包括 legacy 执行。 */
+    executionsWithoutDispatch: number;
+    coverage: 'COMPLETE' | 'PARTIAL' | 'UNAVAILABLE';
+    /** 仅累加完整、对应当前 Dispatch 的供应商报告；无完整报告返回 null。 */
+    reportedTotals: {
+        uncachedInputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    } | null;
+    cost: null;
+    costStatus: 'NOT_RECORDED';
+    sourceRefs: SourceRef[];
+}
+export interface WorkbenchCostRuntime {
+    toolDisclosureMode: 'off' | 'pilot';
+    observerAvailable: boolean;
+}
+/** Public assembly measurements, without runtime/session references or prompt text. */
+export interface WorkbenchPromptCostView {
+    bindingId: string | null;
+    roleType: string;
+    toolsBefore: number | null;
+    toolsAfter: number | null;
+    toolsBytesBefore: number | null;
+    toolsBytesAfter: number | null;
+    sections: {
+        name: string;
+        bytes: number | null;
+    }[];
+    contexts: {
+        name: string;
+        bytes: number | null;
+    }[];
+    partsTruncated: boolean;
+    historyBytes: null;
+    tokenEstimate: null;
+    mode: 'off' | 'pilot' | 'UNKNOWN';
+    reasonCode: string | null;
+}
+export interface WorkbenchCostSummary {
+    additionalRoles: import('../core/cost.js').AdditionalRoleCostSummary | null;
+    budget: import('../core/budget.js').BudgetView | null;
+    prompts: WorkbenchQueue<WorkbenchPromptCostView>;
+    runtime: {
+        toolDisclosureMode: 'off' | 'pilot' | 'UNKNOWN';
+        observerAvailable: boolean | null;
+    };
+}
+export interface WorkbenchPlanReadiness {
+    ready: boolean;
+    reasonCode: string | null;
+    blockingTaskIds: string[];
+    acceptedResults: {
+        taskId: string;
+        attemptNo: number;
+        resultId: string;
+        resultDigest: string;
+        acceptEventId: string;
+    }[];
+}
+export interface WorkbenchPlanView {
+    planId: string;
+    parentTaskId: string;
+    title: string;
+    version: number;
+    digest: string;
+    state: 'PROPOSED' | 'ADOPTED' | 'STALE';
+    mode: 'EXPERT' | 'TEAM';
+    reason: string;
+    integratorBindingId: string;
+    integratorName: string;
+    parentStatus: string;
+    budgetTokens: number;
+    reserveTokens: number;
+    adoptedAt: string | null;
+    integration: WorkbenchPlanReadiness | null;
+    budget: import('../core/collaboration.js').PlanBudgetView | null;
+    items: {
+        key: string;
+        taskId: string;
+        title: string;
+        description: string;
+        acceptanceCriteria: string;
+        territoryId: string;
+        territoryName: string;
+        workerBindingId: string;
+        workerName: string;
+        access: 'READ_ONLY' | 'WRITE';
+        dependsOn: string[];
+        expectedArtifact: string;
+        status: string;
+        readiness: WorkbenchPlanReadiness | null;
+    }[];
+}
+export interface WorkbenchCollaborationView {
+    plans: WorkbenchQueue<WorkbenchPlanView>;
+    pendingAdoptionCount: number;
+    /** Held resources only; absence is not proof that a future start can acquire a workspace. */
+    resources: WorkbenchQueue<{
+        taskId: string;
+        attemptNo: number;
+        access: 'READ_ONLY' | 'WRITE';
+        state: string;
+        recovery: boolean;
+    }>;
+}
+export interface PersonalWorkbenchData {
+    ownerActions: WorkbenchQueue<WorkbenchActionItem>;
+    internalActions: WorkbenchQueue<WorkbenchActionItem>;
+    exceptions: WorkbenchQueue<WorkbenchActionItem>;
+    deliveries: WorkbenchQueue<WorkbenchDeliveryItem>;
+    roles: WorkbenchQueue<WorkbenchRoleItem>;
+    usage: WorkbenchUsageSummary;
+    cost: WorkbenchCostSummary;
+    collaboration: WorkbenchCollaborationView;
+}
+export interface ReadonlySnapshotProjection {
+    overview: ProjectionEnvelope<OverviewProjectionData>;
+    organization: ProjectionEnvelope<OrganizationProjectionData>;
+    executions: ProjectionEnvelope<ExecutionProjectionData>;
+    timeline: ProjectionEnvelope<TimelineItem[]>;
+    attention: ProjectionEnvelope<AttentionItem[]>;
+    workbench: ProjectionEnvelope<PersonalWorkbenchData>;
+}
+/**
+ * S1 只读派生所需的 Host-only 可验证上下文；缺任一项时 action 必须 fail-closed。
+ * `principalSessionId` 由 local-control Host 以 opaque context 注入，不来自浏览器
+ * payload，也不表示 Owner principal。
+ */
+export interface ProjectionSecurityContext {
+    principalSessionId?: string | null;
+    sessionVerified?: boolean;
+    scope?: string[] | null;
+    hostContext?: boolean;
+    commandCoverage?: string[] | null;
+}
 export interface EventView {
     seq: number;
     eventId: string;
@@ -77,15 +416,17 @@ export interface BindingView {
     roleType: string;
     roleName: string;
     runtimeType: string;
-    /** v0.5.2（M1-B/P0-C）：脱敏后的会话标识（如 …8f21）。完整 session id 只进审计事件面，不出普通快照。 */
+    /** v0.5.2（M1-B/P0-C）：脱敏后的会话标识（如 …8f21）；完整 id 不进入公共 GUI JSON。 */
     sessionDisplay: string | null;
     /** 是否已绑定会话（session-bound 模式下该绑定可被验证身份）。 */
     sessionBound: boolean;
-    /** v0.4：会话身份预留字段（模型名 / agent 工具名 / 扩展槽），可空。 */
+    /** v0.4：字段/null shape 兼容；已配置的私有模型值仅返回稳定脱敏标记。 */
     modelName: string | null;
+    /** 字段/null shape 兼容；已配置的私有 agent 值仅返回稳定脱敏标记。 */
     agentName: string | null;
+    /** 保留 object/null shape；敏感 key 递归脱敏，深度、条目、节点与字符串均有界。 */
     sessionMeta: Record<string, unknown> | null;
-    /** v0.6.0（M1-C）：执行配置（ExecutionProfile {provider?, model?}）只读展示；null=未配置（回退全局）。 */
+    /** v0.6.0（M1-C）：保留 ExecutionProfile 字段 shape；配置值脱敏，null=未配置（回退全局）。 */
     executionProfile: {
         provider: string | null;
         model: string | null;
@@ -105,6 +446,7 @@ export interface ClaimView {
     resultId: string;
     attemptNo: number;
     workerBindingId: string | null;
+    /** 与 BindingView 一致的脱敏 session id；字段 shape 保持兼容。 */
     sessionId: string | null;
     /** Worker 自称的结果，仅供展示与审查，不驱动状态。 */
     claimedOutcome: string;
@@ -119,6 +461,7 @@ export interface ExecutionView {
     taskId: string;
     attemptNo: number;
     workerBindingId: string | null;
+    /** 与 BindingView 一致的脱敏 session id；字段 shape 保持兼容。 */
     sessionId: string | null;
     state: string;
     detail: string | null;
@@ -176,6 +519,7 @@ export interface CapabilityDecisionView {
 }
 /** Dispatch Record 投影（RECOVERING 必须如实显示，禁止显示成 Done）。 */
 export interface DispatchView {
+    usage?: import('../core/usage.js').DispatchUsageView | null;
     dispatchId: string;
     leaseId: string;
     executionId: string;
@@ -236,6 +580,12 @@ export interface StageActorView {
     fallbackState: ActorState;
     /** 触发本状态的事件序号，便于 GUI 丢弃过期事件。 */
     sourceSeq: number | null;
+    /**
+     * Evidence is present but cannot be uniquely attributed (for example two
+     * live executions for one binding) or the actor has no exact territory
+     * scope. The renderer must not turn this into a live-success claim.
+     */
+    indeterminate: boolean;
 }
 /** 权限诚实度声明。Beta 若未做主体校验，必须让 GUI 能显示这个徽章。 */
 export interface AuthView {
@@ -274,6 +624,35 @@ export interface SnapshotView {
     recentEvents: EventView[];
     /** v0.8：Runtime Governance 投影（§32）。Schema 非 v4 时为全空数组。 */
     governance: RuntimeGovernanceView;
+    /** v1.0：保留四类证据并 additive 增加 Organization / Execution 摘要。 */
+    projection: ReadonlySnapshotProjection;
+}
+/** v1.0：Task Detail 的 Assignment Ledger 历史；不包含 session/private payload。 */
+export interface TaskAssignmentHistoryView {
+    assignmentId: string;
+    workerBindingId: string;
+    assignedByBindingId: string;
+    assignedAt: string | null;
+    endedAt: string | null;
+    endReason: string | null;
+    previousAssignmentId: string | null;
+    handoffReason: string | null;
+    sourceRefs: SourceRef[];
+}
+/** v1.0：从治理事件还原的 Supervisor decision；HANDOFF 字段均为有界公开引用。 */
+export interface SupervisorDecisionView {
+    seq: number;
+    decision: string;
+    reason: string | null;
+    reviewerBindingId: string | null;
+    reviewedAttemptNo: number | null;
+    claimedOutcome: string | null;
+    fromAssignmentId: string | null;
+    fromWorkerBindingId: string | null;
+    toAssignmentId: string | null;
+    toWorkerBindingId: string | null;
+    sourceRefs: SourceRef[];
+    createdAt: string;
 }
 /** 任务详情：验收标准、尝试历史、Claim、Supervisor 决策、关联事件、下一步动作。 */
 export interface TaskDetailView {
@@ -282,22 +661,23 @@ export interface TaskDetailView {
     task: TaskView;
     territory: TerritoryView | null;
     assignedBinding: BindingView | null;
+    assignments: TaskAssignmentHistoryView[];
     claims: ClaimView[];
     executions: ExecutionView[];
     /** Supervisor 的历次裁定（从 events 还原，不存在 task_reviews 表）。 */
-    reviews: {
-        seq: number;
-        decision: string;
-        reason: string | null;
-        reviewerBindingId: string | null;
-        reviewedAttemptNo: number | null;
-        claimedOutcome: string | null;
-        createdAt: string;
-    }[];
+    reviews: SupervisorDecisionView[];
+    reviewsTruncated: boolean;
     relatedEvents: EventView[];
+    /** 先按本任务取事件再应用窗口，不受其他任务的事件数量影响。 */
+    relatedEventsTruncated: boolean;
+    humanAcceptance: 'NOT_RECORDED';
     allowedActions: AllowedAction[];
     /** v0.8：本任务的 Runtime Governance 投影（Lease/Decision/Dispatch）。 */
     governance: RuntimeGovernanceView;
+    /** Exact single-task attribution only; shared and unattributed units remain outside task totals. */
+    additionalRoleCost: import('../core/cost.js').AdditionalRoleCostSummary | null;
+    /** v0.9 S1：Task Detail 的只读 Projection Envelope。 */
+    projection: ProjectionEnvelope<TaskProjectionData>;
 }
 /** 所有写命令的统一返回。GUI 只读结构化字段，不解析 `message`。 */
 export interface CommandResultView {

package/lib/types/gui/control-contract.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Shared seam between the loopback HTTP server and the direct-Slash-owned
+ * local control broker.
+ *
+ * The values in this file are transport evidence only.  A cookie, CSRF token,
+ * request id, browser payload, or HTTP request never creates Owner or Role
+ * authority.  Only the broker may return the opaque execution context captured
+ * from the direct `/kingdom gui` activation.
+ */
+/** Commands that the loopback GUI may submit after control-session admission. */
+export declare const GUI_SESSION_COMMANDS: readonly ["plan", "assign", "start", "reconcile", "review", "execution.pause", "execution.resume", "execution.abort", "control.revoke"];
+export type GuiSessionCommand = (typeof GUI_SESSION_COMMANDS)[number];
+/** Exact browser-controlled top-level fields for each executable command. */
+export declare const GUI_COMMAND_PAYLOAD_FIELDS: Record<GuiSessionCommand, readonly string[]>;
+/** Authority-shaped keys are forbidden at every structural depth. */
+export declare const GUI_FORBIDDEN_PAYLOAD_FIELDS: readonly ["session", "session_id", "sessionId", "principal", "principal_id", "principalId", "principal_session_id", "principalSessionId", "agent", "agent_id", "agentId", "actor_id", "actorId", "owner", "owner_control", "ownerControl", "owner_capability", "ownerCapability", "authority", "authorization", "cookie", "csrf_token", "csrfToken", "request_id", "requestId", "source_channel", "sourceChannel", "ticket", "launch_ticket", "launchTicket", "control_token", "controlToken", "activation_id", "activationId"];
+export declare class DuplicateJsonKeyError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+/**
+ * Parse one strict JSON object without allowing duplicate keys at any depth.
+ * `JSON.parse` alone cannot enforce this because it silently keeps the last
+ * duplicate value.
+ */
+export declare function parseStrictJsonObject(text: string): Record<string, unknown>;
+export declare const GUI_START_SANDBOX_MODES: readonly ["workspace-write", "read-only"];
+export type GuiStartSandboxMode = (typeof GUI_START_SANDBOX_MODES)[number];
+export declare const GUI_REVIEW_DECISIONS: readonly ["ACCEPT", "REWORK", "FAIL", "HANDOFF"];
+/**
+ * Canonical Owner-only actions advertised by the GUI as discoverable but
+ * non-executable. The retired `setup.basic` HTTP spelling is deliberately not
+ * advertised as an action; it remains deny-only below for fail-closed clients.
+ */
+export declare const GUI_OWNER_ONLY_ACTIONS: readonly ["init", "reset", "ceiling", "territory.create", "territory.delete", "territory.supervisor", "role.bind", "role.unbind", "role.session", "execution-profile"];
+export type GuiOwnerOnlyAction = (typeof GUI_OWNER_ONLY_ACTIONS)[number];
+/** Historical HTTP spellings remain explicit deny-only routes. */
+export declare const GUI_OWNER_ONLY_HTTP_COMMANDS: readonly ["init", "reset", "ceiling", "territory.create", "territory.delete", "territory.supervisor", "role.bind", "role.unbind", "role.session", "execution-profile", "setup.basic", "binding.bind", "binding.unbind", "binding.session"];
+export declare const GUI_OWNER_DIRECT_SLASH_HINTS: Record<GuiOwnerOnlyAction, string>;
+export type GuiControlDisabledReason = 'SESSION_AUTH_REQUIRED' | 'DIRECT_SLASH_REQUIRED';
+export interface GuiControlActionView {
+    executable: boolean;
+    disabledReason: GuiControlDisabledReason | null;
+    /** Loopback command name when executable; Owner-only actions always use null. */
+    command: GuiSessionCommand | null;
+    /** Copyable direct Slash guidance for Owner-only actions only. */
+    directSlashHint: string | null;
+}
+export type GuiControlFailureCode = 'CONTROL_SESSION_REQUIRED' | 'CONTROL_SESSION_EXPIRED' | 'CONTROL_ORIGIN_DENIED' | 'CONTROL_CSRF_DENIED' | 'CONTROL_REPLAY_DENIED' | 'CONTROL_BUSY' | 'CONTROL_TICKET_INVALID';
+export interface GuiControlRequestMeta {
+    host: string | null;
+    origin: string | null;
+    remoteAddress: string | null;
+    fetchSite: string | null;
+}
+export interface GuiControlPublicView {
+    active: true;
+    activationId: string;
+    expiresAt: string;
+    csrfToken: string;
+    roleSessionBound: boolean;
+    commands: string[];
+    reviewDecisions: string[];
+    sandboxModes: string[];
+    actions: Record<string, GuiControlActionView>;
+    disabledReason: null;
+}
+/**
+ * Opaque to the HTTP server.  The broker creates this from direct activation;
+ * browser data cannot construct or amend it.
+ */
+export interface GuiControlExecutionContext {
+    readonly activationId: string;
+    readonly principalSessionId: string;
+    readonly signal: AbortSignal;
+}
+/** Broker-originated read identity; never serialized or accepted from HTTP. */
+export interface GuiControlReadContext {
+    readonly principalSessionId: string | null;
+}
+export interface GuiControlFailure {
+    ok: false;
+    code: GuiControlFailureCode;
+    message: string;
+}
+export interface GuiControlRedeemed {
+    ok: true;
+    cookieValue: string;
+    view: GuiControlPublicView;
+}
+export interface GuiControlInspected {
+    ok: true;
+    view: GuiControlPublicView;
+    readContext: GuiControlReadContext;
+}
+export interface GuiControlAuthorized {
+    ok: true;
+    context: GuiControlExecutionContext;
+    view: GuiControlPublicView;
+    finish(): void;
+}
+export type GuiControlRedeemResult = GuiControlRedeemed | GuiControlFailure;
+export type GuiControlInspectResult = GuiControlInspected | GuiControlFailure;
+export type GuiControlAuthorizeResult = GuiControlAuthorized | GuiControlFailure;
+export interface GuiControlBroker {
+    redeem(ticket: string, meta: GuiControlRequestMeta): GuiControlRedeemResult;
+    inspect(cookieValue: string | null, meta: GuiControlRequestMeta): GuiControlInspectResult;
+    authorize(cookieValue: string | null, csrfToken: string | null, requestId: string | null, meta: GuiControlRequestMeta): GuiControlAuthorizeResult;
+    revoke(cookieValue: string | null): void;
+    dispose(): void;
+}