@cleocode/contracts 2026.6.12 → 2026.6.14

package/src/dispatch/operations-registry.ts

@@ -10,6 +10,8 @@
  */
 
 import { DOCS_LIFECYCLE_STATUSES } from '../operations/docs.js';
+import { OUTPUT_CONTRACTS } from '../operations/output-contracts-data.js';
+import { tasksUpdateInputContract } from '../operations/tasks.js';
 import type { CanonicalDomain, Gateway, OperationDef, ParamDef, Tier } from './operation-def.js';
 
 export type { CanonicalDomain, Gateway, OperationDef, ParamDef, Tier };
@@ -241,6 +243,41 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  // T11785 (epic T11556 · E1-GATEWAY-CRUD) — the FIRST streaming task op. Served
+  // as `GET /v1/tasks/subscribe` → a `text/event-stream` body of
+  // `GatewayStreamEvent` frames (task/board created/updated/deleted lifecycle
+  // events), scoped to an optional saga/parent root. Studio's interactive Kanban
+  // (T11929) and the Pi-TUI board consume it for live updates. The default
+  // source ships a bounded heartbeat producer (stream-sources.ts); the daemon
+  // injects its real origin-tailing source via `registerStreamSource`.
+  {
+    gateway: 'query',
+    domain: 'tasks',
+    operation: 'subscribe',
+    description:
+      'tasks.subscribe (query, streaming) — SSE stream of task/board lifecycle events (created/updated/deleted), optionally scoped to a saga/parent root',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    streaming: true,
+    requiredParams: [],
+    params: [
+      {
+        name: 'root',
+        type: 'string',
+        required: false,
+        description:
+          'Optional saga/parent task ID to scope the event stream to (omit for the whole board)',
+      },
+      {
+        name: 'ticks',
+        type: 'number',
+        required: false,
+        description:
+          'Maximum number of event frames to emit before the terminal `done` frame (default: open-ended until client disconnect)',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'query',
     domain: 'tasks',
@@ -790,6 +827,32 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  // T11921 — gateway SSE streaming on /v1. The agent/worker/board event stream
+  // the Studio Kanban (T11929) + Pi-TUI (T11936) consume as a realtime
+  // transport. Served as `GET /v1/orchestrate/events` → a `text/event-stream`
+  // body of `GatewayStreamEvent` frames terminated by a `done` frame, NOT as a
+  // unary POST. Secrets never touch the wire — the source resolves server-side.
+  {
+    gateway: 'query',
+    domain: 'orchestrate',
+    operation: 'events',
+    description:
+      'orchestrate.events (query, streaming) — SSE stream of agent/worker/board lifecycle events',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    streaming: true,
+    requiredParams: [],
+    params: [
+      {
+        name: 'ticks',
+        type: 'number',
+        required: false,
+        description:
+          'Maximum number of event frames to emit before the terminal `done` frame (default: open-ended until client disconnect)',
+      },
+    ] satisfies ParamDef[],
+  },
   // T811 — IVTR multi-agent enforcement
   {
     gateway: 'query',
@@ -1462,37 +1525,6 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
-  // T5405: WarpChain pipeline operations
-  {
-    gateway: 'query',
-    domain: 'pipeline',
-    operation: 'chain.show',
-    description: 'pipeline.chain.show (query) — get chain definition by ID',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: ['chainId'],
-    params: [
-      {
-        name: 'chainId',
-        type: 'string',
-        required: true,
-        description: 'chainId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'query',
-    domain: 'pipeline',
-    operation: 'chain.list',
-    description: 'pipeline.chain.list (query) — list all chain definitions',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: [],
-    params: [],
-  },
   {
     gateway: 'query',
     domain: 'check',
@@ -1690,26 +1722,6 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
-  // T5405: WarpChain validation query
-  {
-    gateway: 'query',
-    domain: 'check',
-    operation: 'chain.validate',
-    description: 'check.chain.validate (query) — validate a WarpChain definition',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: ['chain'],
-    params: [
-      {
-        name: 'chain',
-        type: 'string',
-        required: true,
-        description: 'chain parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
   // T646: Canon drift detection — CI gate
   {
     gateway: 'query',
@@ -1809,6 +1821,73 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
+  {
+    gateway: 'query',
+    domain: 'admin',
+    operation: 'config.get',
+    description:
+      'admin.config.get (query) — resolve a single config value via the ConfigManifest cascade (T11917)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['key'],
+    params: [
+      {
+        name: 'key',
+        type: 'string',
+        required: true,
+        description: 'Dot-notation config key to read (e.g. "release.branchModel")',
+        cli: { positional: true },
+      },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Cascade slice to read from. Defaults to merged.',
+        enum: ['global', 'project', 'merged'],
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'admin',
+    operation: 'config.list',
+    description:
+      'admin.config.list (query) — resolve the full config cascade and its flattened keys (T11917)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Cascade slice to project. Defaults to merged.',
+        enum: ['global', 'project', 'merged'],
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'admin',
+    operation: 'config.validate',
+    description:
+      'admin.config.validate (query) — schema-validate a scoped config file via its manifest entry (T11917)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Scope to validate (global or project). Defaults to project.',
+        enum: ['global', 'project'],
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'query',
     domain: 'admin',
@@ -2490,10 +2569,18 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
   },
   {
+    // T11784 (epic T11556 · E1-GATEWAY-CRUD) — the OperationDef.params used to
+    // declare ONLY `taskId`, so every other mutable field a Studio form binds
+    // to was invisible to dispatch introspection (`cleo update --describe`, the
+    // SDK `describeOperation`) and silently dropped at the dispatch boundary.
+    // The full mutable-field set is now enumerated here, grounded in
+    // {@link TasksUpdateQueryParams} / {@link TASKS_UPDATE_INPUT_SCHEMA}; a
+    // regression test (operations-registry tasks-update parity) asserts the
+    // param names stay in sync with the schema's `properties`.
     gateway: 'mutate',
     domain: 'tasks',
     operation: 'update',
-    description: 'tasks.update (mutate)',
+    description: 'tasks.update (mutate) — partial update; only supplied fields are mutated',
     tier: 0,
     idempotent: false,
     sessionRequired: false,
@@ -2503,10 +2590,183 @@ export const OPERATIONS: OperationDef[] = [
         name: 'taskId',
         type: 'string',
         required: true,
-        description: 'taskId parameter',
+        description: 'Task ID to update',
         cli: { positional: true },
       },
+      { name: 'title', type: 'string', required: false, description: 'New title (3–500 chars)' },
+      {
+        name: 'description',
+        type: 'string',
+        required: false,
+        description: 'New description',
+        cli: { flag: 'description', short: '-d' },
+      },
+      {
+        name: 'status',
+        type: 'string',
+        required: false,
+        description: 'New status',
+        enum: ['pending', 'active', 'blocked', 'done', 'cancelled'] as const,
+        cli: { flag: 'status', short: '-s' },
+      },
+      {
+        name: 'priority',
+        type: 'string',
+        required: false,
+        description: 'New priority (orthogonal to severity)',
+        enum: ['low', 'medium', 'high', 'critical'] as const,
+        cli: { flag: 'priority', short: '-p' },
+      },
+      { name: 'notes', type: 'string', required: false, description: 'Append a note entry' },
+      {
+        name: 'labels',
+        type: 'array',
+        required: false,
+        description: 'Replace labels (comma-separated)',
+        cli: { flag: 'labels', short: '-l' },
+      },
+      {
+        name: 'addLabels',
+        type: 'array',
+        required: false,
+        description: 'Add labels incrementally',
+      },
+      {
+        name: 'removeLabels',
+        type: 'array',
+        required: false,
+        description: 'Remove labels incrementally',
+      },
+      {
+        name: 'depends',
+        type: 'array',
+        required: false,
+        description: 'Replace dependency task IDs',
+        cli: { flag: 'depends', short: '-D' },
+      },
+      {
+        name: 'addDepends',
+        type: 'array',
+        required: false,
+        description: 'Add dependency task IDs incrementally',
+      },
+      {
+        name: 'removeDepends',
+        type: 'array',
+        required: false,
+        description: 'Remove dependency task IDs incrementally',
+      },
+      {
+        name: 'acceptance',
+        type: 'array',
+        required: false,
+        description: 'Replace acceptance criteria (pipe-separated)',
+      },
+      {
+        name: 'parent',
+        type: 'string',
+        required: false,
+        description: 'Set parent task ID (null/empty promotes to root)',
+      },
+      {
+        name: 'type',
+        type: 'string',
+        required: false,
+        description: 'New hierarchy type',
+        enum: ['saga', 'epic', 'task', 'subtask'] as const,
+        cli: { flag: 'type', short: '-t' },
+      },
+      {
+        name: 'size',
+        type: 'string',
+        required: false,
+        description: 'New scope-size estimate',
+        enum: ['small', 'medium', 'large'] as const,
+      },
+      {
+        name: 'files',
+        type: 'array',
+        required: false,
+        description: 'Replace associated file paths',
+      },
+      {
+        name: 'addFiles',
+        type: 'array',
+        required: false,
+        description: 'Add file paths incrementally',
+      },
+      {
+        name: 'removeFiles',
+        type: 'array',
+        required: false,
+        description: 'Remove file paths incrementally',
+      },
+      {
+        name: 'pipelineStage',
+        type: 'string',
+        required: false,
+        description: 'Set pipeline stage (forward-only)',
+      },
+      {
+        name: 'kind',
+        type: 'string',
+        required: false,
+        description: 'Task kind / intent axis (orthogonal to type)',
+        enum: ['work', 'research', 'experiment', 'bug', 'spike', 'release'] as const,
+      },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Task scope / granularity axis',
+        enum: ['project', 'feature', 'unit'] as const,
+      },
+      {
+        name: 'severity',
+        type: 'string',
+        required: false,
+        description: 'Severity level (orthogonal to priority)',
+        enum: ['P0', 'P1', 'P2', 'P3'] as const,
+      },
+      {
+        name: 'reason',
+        type: 'string',
+        required: false,
+        description: 'Operator override reason for the AC-immutability guard',
+      },
+      {
+        name: 'dependsWaiver',
+        type: 'string',
+        required: false,
+        description: 'Justification to waive the critical-priority --depends requirement',
+      },
+      {
+        name: 'clearBlockedBy',
+        type: 'boolean',
+        required: false,
+        description: 'Clear the free-text blockedBy reason',
+      },
+      {
+        name: 'relates',
+        type: 'array',
+        required: false,
+        description: 'Replace related-task edges ({taskId, type, reason?})',
+      },
+      {
+        name: 'addRelates',
+        type: 'array',
+        required: false,
+        description: 'Add related-task edges without overwriting existing',
+      },
+      {
+        name: 'removeRelates',
+        type: 'array',
+        required: false,
+        description: 'Remove related-task edges by taskId',
+      },
     ] satisfies ParamDef[],
+    inputSchema: tasksUpdateInputContract,
+    outputSchema: OUTPUT_CONTRACTS['tasks.update'],
   },
   {
     gateway: 'mutate',
@@ -2651,18 +2911,110 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  // T11786 (epic T11556 · E1-GATEWAY-CRUD) — bulk task mutate ops the Studio
+  // interactive Kanban (M6) binds to: within-column re-rank, atomic multi-move,
+  // and first-class assignee (distinct from the agent claim lock).
   {
     gateway: 'mutate',
     domain: 'tasks',
-    operation: 'relates.add',
-    description: 'tasks.relates.add (mutate)',
+    operation: 'reorder-rank',
+    description:
+      'tasks.reorder-rank (mutate) — within-column positional re-rank from an explicit top-to-bottom task-ID order (Kanban drag-reorder)',
     tier: 1,
     idempotent: false,
     sessionRequired: false,
-    requiredParams: ['taskId', 'type'],
+    requiredParams: ['orderedIds'],
     params: [
       {
-        name: 'taskId',
+        name: 'orderedIds',
+        type: 'array',
+        required: true,
+        description:
+          'Ordered task IDs describing the desired top-to-bottom column order; each task position is set to its 1-based index',
+      },
+    ] satisfies ParamDef[],
+    outputSchema: OUTPUT_CONTRACTS['tasks.reorder-rank'],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'bulk-move',
+    description:
+      'tasks.bulk-move (mutate) — atomically move N tasks to a new status and/or pipeline stage in a single transaction (Kanban multi-card column move)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['taskIds'],
+    params: [
+      {
+        name: 'taskIds',
+        type: 'array',
+        required: true,
+        description: 'Task IDs to move (all-or-nothing; any failure rolls back every move)',
+      },
+      {
+        name: 'status',
+        type: 'string',
+        required: false,
+        description: 'Target lifecycle status applied to every task',
+        enum: [
+          'pending',
+          'active',
+          'blocked',
+          'done',
+          'cancelled',
+          'archived',
+          'proposed',
+        ] as const,
+      },
+      {
+        name: 'pipelineStage',
+        type: 'string',
+        required: false,
+        description: 'Target pipeline stage applied to every task (forward-only)',
+      },
+    ] satisfies ParamDef[],
+    outputSchema: OUTPUT_CONTRACTS['tasks.bulk-move'],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'assignee',
+    description:
+      'tasks.assignee (mutate) — set/clear a first-class human assignee (DISTINCT from the agent claim/unclaim lock; pass assignee:null to clear)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['taskId'],
+    params: [
+      {
+        name: 'taskId',
+        type: 'string',
+        required: true,
+        description: 'Task ID whose assignee is being set or cleared',
+        cli: { positional: true },
+      },
+      {
+        name: 'assignee',
+        type: 'string',
+        required: false,
+        description: 'Assignee to set; omit / empty / null clears the assignee',
+      },
+    ] satisfies ParamDef[],
+    outputSchema: OUTPUT_CONTRACTS['tasks.assignee'],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'relates.add',
+    description: 'tasks.relates.add (mutate)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['taskId', 'type'],
+    params: [
+      {
+        name: 'taskId',
         type: 'string',
         required: true,
         description: 'taskId parameter',
@@ -4248,77 +4600,6 @@ export const OPERATIONS: OperationDef[] = [
       { name: 'force', type: 'boolean', required: false, description: 'Required safety flag' },
     ],
   },
-  // T5405: WarpChain pipeline mutate operations
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.add',
-    description: 'pipeline.chain.add (mutate) — store a validated chain definition',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['chain'],
-    params: [
-      {
-        name: 'chain',
-        type: 'string',
-        required: true,
-        description: 'chain parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.instantiate',
-    description: 'pipeline.chain.instantiate (mutate) — create chain instance for epic',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['chainId', 'epicId'],
-    params: [
-      {
-        name: 'chainId',
-        type: 'string',
-        required: true,
-        description: 'chainId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'epicId',
-        type: 'string',
-        required: true,
-        description: 'epicId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.advance',
-    description: 'pipeline.chain.advance (mutate) — advance instance to next stage',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['instanceId', 'nextStage'],
-    params: [
-      {
-        name: 'instanceId',
-        type: 'string',
-        required: true,
-        description: 'instanceId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'nextStage',
-        type: 'string',
-        required: true,
-        description: 'nextStage parameter',
-      },
-    ] satisfies ParamDef[],
-  },
   {
     gateway: 'mutate',
     domain: 'check',
@@ -4553,6 +4834,32 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  {
+    gateway: 'mutate',
+    domain: 'admin',
+    operation: 'config.unset',
+    description:
+      'admin.config.unset (mutate) — remove a key from a scoped config file (idempotent) (T11917)',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['key'],
+    params: [
+      {
+        name: 'key',
+        type: 'string',
+        required: true,
+        description: 'Dot-notation config key to remove',
+        cli: { positional: true },
+      },
+      {
+        name: 'global',
+        type: 'boolean',
+        required: false,
+        description: 'Remove from the global file instead of the project file',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'query',
     domain: 'admin',
@@ -6603,54 +6910,6 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
-  // orchestrate — tessera template operations (T5411)
-  // tessera.show removed — merged into tessera.list via optional id param (T5615)
-  {
-    gateway: 'query',
-    domain: 'orchestrate',
-    operation: 'tessera.list',
-    description:
-      'orchestrate.tessera.list (query) — list Tessera templates; absorbs tessera.show via optional id param',
-    tier: 1,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: [],
-    params: [
-      {
-        name: 'id',
-        type: 'string',
-        required: false,
-        description: 'Optional template ID for single-item lookup (replaces tessera.show)',
-      },
-    ],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'orchestrate',
-    operation: 'tessera.instantiate',
-    description:
-      'orchestrate.tessera.instantiate (mutate) — instantiate a Tessera template into a chain instance',
-    tier: 1,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['templateId', 'epicId'],
-    params: [
-      {
-        name: 'templateId',
-        type: 'string',
-        required: true,
-        description: 'templateId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'epicId',
-        type: 'string',
-        required: true,
-        description: 'epicId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
   // orchestrate — Wave 7a dispatch ops (T408, T409, T410, T415)
   {
     gateway: 'query',
@@ -8956,4 +9215,652 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+
+  // ── selfimprove mutate: run (T11889 / T11889-D — the self-dogfooding loop) ──
+  // Boots ONE sandbox → replays the named canned scenario → diffs result
+  // envelopes vs the golden → on a regression emits ONE leased `selfimprove_dhq`
+  // row and opens ONE DRAFT PR. The walking skeleton's default scenario is
+  // query-only so the in-process replay never mutates. DEFAULT OFF: without
+  // `execute` the loop runs DRY-RUN (replay + diff + report; NO DB write, NO PR).
+  // The CORE engine (`runSelfImprove`) owns boot/replay/diff/persist/egress +
+  // the budget + circuit-breaker; the dispatch handler is a thin delegate that
+  // supplies the in-process `ReplayDispatch` port (Gate-6). `sessionRequired`
+  // links each run to its origin session for provenance.
+  {
+    gateway: 'mutate',
+    domain: 'selfimprove',
+    operation: 'run',
+    description:
+      'selfimprove.run (mutate) — boot ONE sandbox, replay a canned dogfood scenario, diff vs golden; on regression emit ONE leased selfimprove_dhq row + ONE DRAFT PR. Default OFF — requires --execute (else DRY-RUN). Budget-capped + circuit-broken (T11889 / T11889-D).',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: true,
+    requiredParams: ['scenario'],
+    params: [
+      {
+        name: 'scenario',
+        type: 'string',
+        required: true,
+        description: 'Canned dogfood scenario name to replay (e.g. dhq-replay-find)',
+      },
+      {
+        name: 'execute',
+        type: 'boolean',
+        required: false,
+        description:
+          'Permit mutation (leased DHQ UPSERT) + egress (draft PR). DEFAULT false ⇒ DRY-RUN (replay + diff + report only — no DB write, no PR).',
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description:
+          'Force DRY-RUN explicitly (no DB write, no PR). Equivalent to omitting --execute; the loop is default-OFF.',
+      },
+      {
+        name: 'backend',
+        type: 'string',
+        required: false,
+        description:
+          "Confinement backend preference: 'gondolin' (micro-VM; degrades to the in-process guarded env when VM infra is absent — the CI path) | 'guarded'. Default: gondolin.",
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // ── service domain: universal service-vault OAuth flow (T11939 · epic T11765) ──
+  // Four verbs driving the declarative SERVICE_PROVIDERS registry: auth-url (query
+  // — build a PKCE authorization URL), exchange (mutate — persist encrypted tokens
+  // from an auth code), refresh (mutate — renew an access token honoring the
+  // per-provider RefreshConfig), self-heal (mutate — resolve + transparently
+  // refresh a past-expiry connection). The flow lives in CORE (store/service-oauth.ts).
+  {
+    gateway: 'query',
+    domain: 'service',
+    operation: 'auth-url',
+    description:
+      'service.auth-url (query) — build a PKCE OAuth authorization URL for a service provider; returns the URL + the code verifier + state to round-trip into service.exchange.',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description:
+          'Service provider key (e.g. github, google, notion) — must be in SERVICE_PROVIDERS.',
+      },
+      {
+        name: 'state',
+        type: 'string',
+        required: false,
+        description: 'Opaque CSRF state to embed; a random value is generated when omitted.',
+      },
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Scope override (e.g. a BYOC custom scope). Defaults to the provider scope.',
+      },
+      {
+        name: 'redirectUri',
+        type: 'string',
+        required: false,
+        description: 'Redirect URI override. Defaults to the provider loopback redirect.',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'service',
+    operation: 'exchange',
+    description:
+      'service.exchange (mutate) — exchange an OAuth authorization code (+ PKCE verifier) for tokens and PERSIST them encryptGlobal-encrypted into service_connections. Returns the non-secret connection identity.',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider', 'code', 'codeVerifier', 'redirectUri'],
+    params: [
+      { name: 'provider', type: 'string', required: true, description: 'Service provider key.' },
+      {
+        name: 'code',
+        type: 'string',
+        required: true,
+        description: 'Authorization code from the redirect callback.',
+      },
+      {
+        name: 'codeVerifier',
+        type: 'string',
+        required: true,
+        description: 'PKCE code verifier from service.auth-url (round-tripped).',
+      },
+      {
+        name: 'redirectUri',
+        type: 'string',
+        required: true,
+        description: 'Redirect URI used in service.auth-url (must match).',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: 'Connection label, unique within the provider. Defaults to "default".',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'service',
+    operation: 'refresh',
+    description:
+      'service.refresh (mutate) — refresh a service connection access token honoring the per-provider RefreshConfig (Form/Json × Body/BasicAuth, plus github-app / service-account-jwt / client-credentials variants); re-encrypts + persists the new blob.',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['agentId', 'provider', 'label'],
+    params: [
+      {
+        name: 'agentId',
+        type: 'string',
+        required: true,
+        description: 'Agent requesting the refresh (trust-gated).',
+      },
+      { name: 'provider', type: 'string', required: true, description: 'Service provider key.' },
+      { name: 'label', type: 'string', required: true, description: 'Connection label.' },
+      {
+        name: 'approved',
+        type: 'boolean',
+        required: false,
+        description: 'Out-of-band manual-approval flag forwarded to the trust gate.',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'service',
+    operation: 'self-heal',
+    description:
+      'service.self-heal (mutate) — resolve a service connection and, when its expires_at is past, transparently refresh + re-encrypt + persist; returns a fresh sealed-credential reference (agents never see a stale token).',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['agentId', 'provider', 'label'],
+    params: [
+      {
+        name: 'agentId',
+        type: 'string',
+        required: true,
+        description: 'Agent requesting the connection (trust-gated).',
+      },
+      { name: 'provider', type: 'string', required: true, description: 'Service provider key.' },
+      { name: 'label', type: 'string', required: true, description: 'Connection label.' },
+      {
+        name: 'approved',
+        type: 'boolean',
+        required: false,
+        description: 'Out-of-band manual-approval flag forwarded to the trust gate.',
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // ── service domain: user-facing service-vault CLI verbs (T11941 · M2-W4) ──
+  // Four verbs making the universal vault USABLE from the CLI: connect (mutate —
+  // store a credential via token-direct or paste-code OAuth exchange), list
+  // (query — redacted connection views, NEVER the token), revoke (mutate — hard
+  // delete + cascade agent grants), status (query — connection health: expired?
+  // needsRefresh?). Thin handlers delegate to CORE accessor + service-oauth.
+  {
+    gateway: 'mutate',
+    domain: 'service',
+    operation: 'connect',
+    description:
+      'service.connect (mutate) — connect a service credential: store an already-obtained token (--token) OR exchange an OAuth authorization code (--paste-code + --code-verifier + --redirect-uri). Persists the token blob encryptGlobal-encrypted; returns the NON-SECRET connection identity (never the token).',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'Service provider key (e.g. github, google, notion).',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: "Connection label, unique within the provider. Defaults to 'default'.",
+      },
+      {
+        name: 'token',
+        type: 'string',
+        required: false,
+        description: 'Direct access token to store (token-direct mode). SECRET — never echoed.',
+      },
+      {
+        name: 'refreshToken',
+        type: 'string',
+        required: false,
+        description: 'Optional refresh token paired with --token. SECRET.',
+      },
+      {
+        name: 'expiresAt',
+        type: 'string',
+        required: false,
+        description: 'ISO-8601 access-token expiry (token-direct mode).',
+      },
+      {
+        name: 'code',
+        type: 'string',
+        required: false,
+        description: 'OAuth authorization code from the redirect callback (paste-code mode).',
+      },
+      {
+        name: 'codeVerifier',
+        type: 'string',
+        required: false,
+        description: 'PKCE code verifier from service.auth-url, round-tripped (paste-code mode).',
+      },
+      {
+        name: 'redirectUri',
+        type: 'string',
+        required: false,
+        description: 'Redirect URI used in service.auth-url; must match (paste-code mode).',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'service',
+    operation: 'list',
+    description:
+      'service.list (query) — list service connections as NON-SECRET views (provider/label/status/scopes/expiresAt/hasCredentials). The decrypted token is NEVER surfaced.',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: false,
+        description: 'Optional provider filter; lists all providers when omitted.',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'service',
+    operation: 'revoke',
+    description:
+      'service.revoke (mutate) — DELETE a service connection and CASCADE its agent_service_grants. Returns the {count, deleted, grantsRemoved} envelope (count=0 when no such connection).',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider', 'label'],
+    params: [
+      { name: 'provider', type: 'string', required: true, description: 'Service provider key.' },
+      {
+        name: 'label',
+        type: 'string',
+        required: true,
+        description: 'Connection label to revoke.',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'service',
+    operation: 'status',
+    description:
+      'service.status (query) — report connection health: each connection adds `expired` + `needsRefresh` booleans computed from expires_at. NON-SECRET; never surfaces a token.',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: false,
+        description: 'Optional provider filter; reports all connections when omitted.',
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // ── 5-entity provider experience (T11700 · epic T11666 · North-Star §2) ──
+  // The addressable Provider / Alias / Account / Model / Profile surface. Each op
+  // dispatches to the CORE entity-ops layer (llm/entity-ops.ts), which is a thin
+  // composition over the ALREADY-MERGED accessors: the credential pool
+  // (account.* — secret-bearing, redacted to tokenPreview), the declarative
+  // `providers` table (#1039), the `models_catalog` table (#1037), and the
+  // resolver-consumed `llm.profiles[name]` config (profile.*). The secret-bearing
+  // ops carry NO `mcpExposed` flag → they are MCP-default-denied (AC5/AC7); read
+  // ops are also unary CLI/RPC/HTTP (no `mcpExposed`), keeping the MCP surface
+  // curated. INPUT + OUTPUT contracts live in contracts/operations/entities.ts.
+
+  // account.* — the credential pool (the rename/successor of the secret-bearing
+  // `llm` pool ops). `account.add` is SECRET-BEARING (cli-only; MCP-denied).
+  {
+    gateway: 'mutate',
+    domain: 'account',
+    operation: 'add',
+    description:
+      'account.add (mutate) — store a pooled provider credential. SECRET-BEARING (cli-only): accepts an API key / OAuth token and persists it encrypted; returns the NON-SECRET redacted view (tokenPreview last-4 ONLY — never the raw secret).',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider', 'token'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'LLM provider transport key (e.g. anthropic, openai).',
+        cli: { positional: true },
+      },
+      {
+        name: 'token',
+        type: 'string',
+        required: true,
+        description: 'API key or OAuth bearer token to persist. SECRET — never echoed.',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: "Account label, unique within the provider (default: 'default').",
+      },
+      {
+        name: 'baseUrl',
+        type: 'string',
+        required: false,
+        description: 'Optional override for the provider base URL.',
+      },
+      {
+        name: 'authType',
+        type: 'string',
+        required: false,
+        description: "Explicit auth-type override ('api_key' | 'oauth' | 'aws_sdk').",
+      },
+      {
+        name: 'priority',
+        type: 'number',
+        required: false,
+        description: 'Optional priority override (lower wins).',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'account',
+    operation: 'list',
+    description:
+      'account.list (query) — list pooled accounts as NON-SECRET redacted views (provider/label/authType/tokenPreview). The decrypted secret is NEVER surfaced.',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: false,
+        description: 'Optional provider filter; lists all providers when omitted.',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'account',
+    operation: 'remove',
+    description:
+      'account.remove (mutate) — delete a (provider, label) account from the pool. Returns the {count, deleted} envelope (count=0 when absent — idempotent).',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['provider', 'label'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'LLM provider transport key.',
+        cli: { positional: true },
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: true,
+        description: 'Account label to remove.',
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // provider.* — the declarative `providers` table (#1039) + alias resolution.
+  {
+    gateway: 'query',
+    domain: 'provider',
+    operation: 'list',
+    description:
+      'provider.list (query) — list every declarative provider as a NON-SECRET view (id/displayName/aliases/authMethods/modelsDevId) from the providers table.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'provider',
+    operation: 'show',
+    description:
+      'provider.show (query) — resolve ONE provider by id OR case-insensitive alias against the declarative alias index; returns the provider view + the id/alias matched.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['provider'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'Provider id OR a case-insensitive alias.',
+        cli: { positional: true },
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'provider',
+    operation: 'connect',
+    description:
+      'provider.connect (mutate) — connect a provider by storing a token as one of its accounts (token-direct). SECRET-BEARING (cli-only): resolves the provider (id/alias) then delegates to the secret-bearing account write; returns the NON-SECRET account identity (never the raw token). OAuth flows route through `cleo service`.',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['provider'],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'Provider id or alias to connect.',
+        cli: { positional: true },
+      },
+      {
+        name: 'token',
+        type: 'string',
+        required: false,
+        description: 'Direct API key / bearer token to store (token-direct mode). SECRET.',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: "Account label to create (default: 'default').",
+      },
+      {
+        name: 'authType',
+        type: 'string',
+        required: false,
+        description: "Explicit auth-type override ('api_key' | 'oauth' | 'aws_sdk').",
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // model.* — the models.dev catalog (`models_catalog` table, #1037). QUERY-ONLY.
+  {
+    gateway: 'query',
+    domain: 'model',
+    operation: 'query',
+    description:
+      'model.query (query) — read the models.dev catalog (models_catalog table) newest-first by release date; optionally filtered by provider (models.dev id) and capped by --limit. Returns NON-SECRET catalog views.',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'provider',
+        type: 'string',
+        required: false,
+        description:
+          'Optional provider filter (models.dev id); queries all providers when omitted.',
+      },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Optional cap on the number of rows returned (newest-first).',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'model',
+    operation: 'show',
+    description:
+      'model.show (query) — resolve ONE catalog model by id; returns {found, model} (found=false when the id is absent — not an error).',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['model'],
+    params: [
+      {
+        name: 'model',
+        type: 'string',
+        required: true,
+        description: 'Model id (catalog key) to resolve.',
+        cli: { positional: true },
+      },
+    ] satisfies ParamDef[],
+  },
+
+  // profile.* — the named binding account+model[+params+role], persisted into
+  // `llm.profiles[name]` (the resolver-consumed config SSoT).
+  {
+    gateway: 'mutate',
+    domain: 'profile',
+    operation: 'create',
+    description:
+      'profile.create (mutate) — bind an account + model into a named, addressable profile. Validates the binding (the pinned account must exist; the model must be in the catalog) then persists into llm.profiles[name]. Returns {count, created, profile}.',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['name', 'provider', 'model'],
+    params: [
+      {
+        name: 'name',
+        type: 'string',
+        required: true,
+        description: 'Profile name (the addressable handle).',
+        cli: { positional: true },
+      },
+      {
+        name: 'provider',
+        type: 'string',
+        required: true,
+        description: 'Provider transport the bound account belongs to.',
+      },
+      {
+        name: 'model',
+        type: 'string',
+        required: true,
+        description: 'Model id to bind (validated against the catalog).',
+      },
+      {
+        name: 'label',
+        type: 'string',
+        required: false,
+        description: 'Account label to pin (the credential binding). Validated to exist.',
+      },
+      {
+        name: 'role',
+        type: 'string',
+        required: false,
+        description: 'Optional role this profile occupies (extraction | consolidation | …).',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'query',
+    domain: 'profile',
+    operation: 'list',
+    description:
+      'profile.list (query) — list every named profile from llm.profiles (name + provider + model + optional credentialLabel).',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'profile',
+    operation: 'pin',
+    description:
+      'profile.pin (mutate) — pin a role to a named profile (llm.roles[role].profile). The role must be a valid background role and the profile must already exist.',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['name', 'role'],
+    params: [
+      {
+        name: 'name',
+        type: 'string',
+        required: true,
+        description: 'Profile name to pin (must exist).',
+        cli: { positional: true },
+      },
+      {
+        name: 'role',
+        type: 'string',
+        required: true,
+        description: 'Role to pin to this profile (extraction | consolidation | derivation | …).',
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    gateway: 'mutate',
+    domain: 'profile',
+    operation: 'use',
+    description:
+      'profile.use (mutate) — set a named profile as the global default binding (llm.defaultProfile). The profile must already exist.',
+    tier: 2,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['name'],
+    params: [
+      {
+        name: 'name',
+        type: 'string',
+        required: true,
+        description: 'Profile name to mark as default (must exist).',
+        cli: { positional: true },
+      },
+    ] satisfies ParamDef[],
+  },
 ];