@cleocode/contracts 2026.6.12 → 2026.6.14

package/src/operations/service.ts

@@ -0,0 +1,360 @@
+/**
+ * Service-vault CLI operation contracts — INPUT + OUTPUT schemas (T11941).
+ *
+ * The schema-first I/O contracts for the four user-facing service-vault CLI
+ * verbs (`cleo service connect|list|revoke|status`). They live HERE in the
+ * `contracts` leaf package — alongside `tasks.ts` and the OUTPUT-contracts
+ * registry — so every consumer (CLI `--describe`, the SDK `describeOperation`,
+ * REST clients) resolves the I/O shape against ONE source of truth.
+ *
+ * AC4 (T11941): each new op carries an INPUT and an OUTPUT schema and appears in
+ * the output-contract data. `connect`/`list`/`revoke`/`status` are registered in
+ * `INPUT_CONTRACTS` (core) and `OUTPUT_CONTRACTS` (this package) so
+ * `cleo service <verb> --describe` resolves a non-null contract pair.
+ *
+ * ## Secrets never surfaced
+ *
+ * Every OUTPUT schema describes a NON-SECRET view: `list`/`status` carry
+ * `provider`/`label`/`status`/`scopes`/`expiresAt`/`hasCredentials` only —
+ * NEVER the decrypted token. `connect` returns the non-secret connection
+ * identity. `revoke` returns the `{count, deleted, grantsRemoved}` cascade
+ * report. There is no `--field` pointer that resolves to a token, by design.
+ *
+ * @packageDocumentation
+ * @module @cleocode/contracts/operations/service
+ *
+ * @epic T11765
+ * @saga T10409
+ * @task T11941 — M2-W4 service CLI verbs
+ */
+
+import type { JsonSchema, OperationInputContract } from './input-contract.js';
+import type { OperationOutputContract } from './output-contract.js';
+
+// ---------------------------------------------------------------------------
+// service.connect — store a service credential (token-direct or paste-code)
+// ---------------------------------------------------------------------------
+
+/**
+ * Accepted input shape for `service.connect`.
+ *
+ * Two non-interactive modes (v1, browser-free + testable):
+ *   - token-direct: `provider` + `token` (+ optional `refreshToken`, `expiresAt`,
+ *     `scopes`) — stores the token blob `encryptGlobal`-encrypted.
+ *   - paste-code: `provider` + `code` + `codeVerifier` + `redirectUri` — runs the
+ *     OAuth `exchangeCode` dance (the interactive flow is a thin wrapper over it).
+ *
+ * `additionalProperties: false` so a typo'd flag is rejected loudly (DHQ-033).
+ *
+ * @task T11941
+ */
+export const SERVICE_CONNECT_INPUT_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: ['provider'],
+  additionalProperties: false,
+  properties: {
+    provider: {
+      type: 'string',
+      minLength: 1,
+      description: 'Service provider key (e.g. github, google, notion).',
+    },
+    label: {
+      type: 'string',
+      description: "Connection label, unique within the provider (default: 'default').",
+    },
+    token: {
+      type: 'string',
+      description:
+        'Direct access token to store (token-direct mode). SECRET — never logged/echoed.',
+    },
+    refreshToken: {
+      type: 'string',
+      description: 'Optional refresh token paired with --token. SECRET.',
+    },
+    expiresAt: {
+      type: 'string',
+      description: 'ISO-8601 access-token expiry (token-direct mode).',
+    },
+    scopes: {
+      type: 'array',
+      items: { type: 'string' },
+      description: 'Granted scope list (non-secret).',
+    },
+    code: {
+      type: 'string',
+      description: 'OAuth authorization code from the redirect callback (paste-code mode).',
+    },
+    codeVerifier: {
+      type: 'string',
+      description: 'PKCE code verifier from service.auth-url, round-tripped (paste-code mode).',
+    },
+    redirectUri: {
+      type: 'string',
+      description: 'Redirect URI used in service.auth-url; must match (paste-code mode).',
+    },
+  },
+};
+
+/** Schema-first INPUT contract for `service.connect`. */
+export const serviceConnectInputContract: OperationInputContract<Record<string, unknown>> = {
+  operation: 'service.connect',
+  schema: SERVICE_CONNECT_INPUT_SCHEMA,
+  examples: [
+    {
+      name: 'token-direct',
+      value: { provider: 'github', token: 'gho_xxx', label: 'personal' },
+      description: 'Store an already-obtained access token (browser-free v1).',
+    },
+    {
+      name: 'paste-code',
+      value: {
+        provider: 'github',
+        code: 'auth-code',
+        codeVerifier: 'pkce-verifier',
+        redirectUri: 'http://127.0.0.1:0/callback',
+      },
+      description: 'Exchange an OAuth code + PKCE verifier for tokens.',
+    },
+  ],
+};
+
+/** OUTPUT contract for `service.connect` — the non-secret mutate envelope. */
+export const serviceConnectOutputContract: OperationOutputContract = {
+  operation: 'service.connect',
+  shapeNote:
+    'Mutate envelope: count=1, created=[connectionId]. `connection` carries the NON-SECRET identity (provider/label/expiresAt). No token is ever returned.',
+  dataSchema: {
+    type: 'object',
+    required: ['count', 'created'],
+    additionalProperties: true,
+    properties: {
+      count: { type: 'number', description: 'Number of connections created/updated (1).' },
+      created: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'The connection id(s) created/updated, as strings.',
+      },
+      connection: {
+        type: 'object',
+        description: 'Non-secret connection identity.',
+        properties: {
+          connectionId: { type: 'number' },
+          provider: { type: 'string' },
+          label: { type: 'string' },
+          expiresAt: { type: ['string', 'null'] },
+        },
+      },
+    },
+  },
+  fieldPointers: [
+    '/data/count',
+    '/data/created/0',
+    '/data/connection/provider',
+    '/data/connection/label',
+    '/data/connection/expiresAt',
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// service.list — redacted connection views
+// ---------------------------------------------------------------------------
+
+/** Accepted input shape for `service.list`. */
+export const SERVICE_LIST_INPUT_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [],
+  additionalProperties: false,
+  properties: {
+    provider: {
+      type: 'string',
+      description: 'Optional provider filter; lists all providers when omitted.',
+    },
+  },
+};
+
+/** Schema-first INPUT contract for `service.list`. */
+export const serviceListInputContract: OperationInputContract<Record<string, unknown>> = {
+  operation: 'service.list',
+  schema: SERVICE_LIST_INPUT_SCHEMA,
+  examples: [
+    { name: 'all', value: {}, description: 'List every service connection (redacted).' },
+    { name: 'one-provider', value: { provider: 'github' }, description: 'Filter to one provider.' },
+  ],
+};
+
+/** The redacted per-connection view schema (shared by list + status). */
+const SERVICE_CONNECTION_VIEW_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: ['provider', 'label', 'status', 'scopes', 'hasCredentials'],
+  additionalProperties: true,
+  properties: {
+    id: { type: 'number' },
+    provider: { type: 'string' },
+    label: { type: 'string' },
+    status: { type: 'string', enum: ['active', 'expired', 'revoked'] },
+    scopes: { type: 'array', items: { type: 'string' } },
+    expiresAt: { type: ['string', 'null'] },
+    connectedAt: { type: 'string' },
+    updatedAt: { type: 'string' },
+    hasCredentials: {
+      type: 'boolean',
+      description: 'Whether a credential blob is present — NEVER the token itself.',
+    },
+  },
+};
+
+/** OUTPUT contract for `service.list` — redacted connection views. */
+export const serviceListOutputContract: OperationOutputContract = {
+  operation: 'service.list',
+  shapeNote:
+    'connections[] are NON-SECRET views — provider/label/status/scopes/expiresAt/hasCredentials only. The decrypted token is NEVER present in any field.',
+  dataSchema: {
+    type: 'object',
+    required: ['connections'],
+    additionalProperties: true,
+    properties: {
+      connections: {
+        type: 'array',
+        items: SERVICE_CONNECTION_VIEW_SCHEMA,
+        description: 'Redacted connection views.',
+      },
+    },
+  },
+  fieldPointers: [
+    '/data/connections',
+    '/data/connections/0/provider',
+    '/data/connections/0/label',
+    '/data/connections/0/status',
+    '/data/connections/0/expiresAt',
+    '/data/connections/0/hasCredentials',
+  ],
+};
+
+// ---------------------------------------------------------------------------
+// service.revoke — hard delete + cascade grants
+// ---------------------------------------------------------------------------
+
+/** Accepted input shape for `service.revoke`. */
+export const SERVICE_REVOKE_INPUT_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: ['provider', 'label'],
+  additionalProperties: false,
+  properties: {
+    provider: { type: 'string', minLength: 1, description: 'Service provider key.' },
+    label: { type: 'string', minLength: 1, description: 'Connection label to revoke.' },
+  },
+};
+
+/** Schema-first INPUT contract for `service.revoke`. */
+export const serviceRevokeInputContract: OperationInputContract<Record<string, unknown>> = {
+  operation: 'service.revoke',
+  schema: SERVICE_REVOKE_INPUT_SCHEMA,
+  examples: [
+    {
+      name: 'revoke',
+      value: { provider: 'github', label: 'personal' },
+      description: 'Delete the connection and cascade its agent grants.',
+    },
+  ],
+};
+
+/** OUTPUT contract for `service.revoke` — the cascade-delete report. */
+export const serviceRevokeOutputContract: OperationOutputContract = {
+  operation: 'service.revoke',
+  shapeNote:
+    'Mutate envelope: count=1 + deleted=[provider:label] on success (0 + [] when no such connection). `grantsRemoved` counts the cascaded agent_service_grants rows.',
+  dataSchema: {
+    type: 'object',
+    required: ['count', 'deleted'],
+    additionalProperties: true,
+    properties: {
+      count: { type: 'number', description: '1 when a connection was deleted, else 0.' },
+      deleted: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'The `provider:label` identifier(s) deleted.',
+      },
+      grantsRemoved: {
+        type: 'number',
+        description: 'How many agent_service_grants rows were cascaded-deleted.',
+      },
+    },
+  },
+  fieldPointers: ['/data/count', '/data/deleted/0', '/data/grantsRemoved'],
+};
+
+// ---------------------------------------------------------------------------
+// service.status — connection health (expired? needs refresh?)
+// ---------------------------------------------------------------------------
+
+/** Accepted input shape for `service.status`. */
+export const SERVICE_STATUS_INPUT_SCHEMA: JsonSchema = {
+  type: 'object',
+  required: [],
+  additionalProperties: false,
+  properties: {
+    provider: {
+      type: 'string',
+      description: 'Optional provider filter; reports all connections when omitted.',
+    },
+  },
+};
+
+/** Schema-first INPUT contract for `service.status`. */
+export const serviceStatusInputContract: OperationInputContract<Record<string, unknown>> = {
+  operation: 'service.status',
+  schema: SERVICE_STATUS_INPUT_SCHEMA,
+  examples: [
+    { name: 'all', value: {}, description: 'Health of every connection.' },
+    {
+      name: 'one-provider',
+      value: { provider: 'github' },
+      description: 'Health for one provider.',
+    },
+  ],
+};
+
+/** OUTPUT contract for `service.status` — per-connection health. */
+export const serviceStatusOutputContract: OperationOutputContract = {
+  operation: 'service.status',
+  shapeNote:
+    'connections[] are NON-SECRET health views: each adds `expired` + `needsRefresh` booleans computed from expiresAt. No token is ever present.',
+  dataSchema: {
+    type: 'object',
+    required: ['connections'],
+    additionalProperties: true,
+    properties: {
+      connections: {
+        type: 'array',
+        items: {
+          type: 'object',
+          required: ['provider', 'label', 'status', 'expired', 'needsRefresh'],
+          additionalProperties: true,
+          properties: {
+            provider: { type: 'string' },
+            label: { type: 'string' },
+            status: { type: 'string', enum: ['active', 'expired', 'revoked'] },
+            expiresAt: { type: ['string', 'null'] },
+            expired: {
+              type: 'boolean',
+              description: 'True when expiresAt is in the past (or status=expired).',
+            },
+            needsRefresh: {
+              type: 'boolean',
+              description: 'True when the connection is expired and has stored credentials.',
+            },
+            hasCredentials: { type: 'boolean' },
+          },
+        },
+      },
+    },
+  },
+  fieldPointers: [
+    '/data/connections',
+    '/data/connections/0/provider',
+    '/data/connections/0/label',
+    '/data/connections/0/status',
+    '/data/connections/0/expired',
+    '/data/connections/0/needsRefresh',
+  ],
+};

package/src/operations/tasks.ts

@@ -1078,6 +1078,113 @@ export interface TasksReorderDispatchResult {
   totalSiblings: number;
 }
 
+// ---------------------------------------------------------------------------
+// tasks.reorder-rank / tasks.bulk-move / tasks.assignee
+// (T11786 · epic T11556 · E1-GATEWAY-CRUD — bulk task mutate ops Studio's
+// interactive Kanban binds to)
+// ---------------------------------------------------------------------------
+
+/**
+ * Params for `tasks.reorder-rank` — explicit within-column positional ordering.
+ *
+ * Unlike `tasks.reorder` (which moves ONE task to a 1-based index and recomputes
+ * every sibling), this op takes the FULL desired ordering of a sibling/column
+ * scope as a task-ID array and writes each task's `position` to its index in the
+ * array. This is the Kanban "drag a card and the whole column re-ranks" shape:
+ * the client sends the new column order, the op persists it in one pass.
+ *
+ * @task T11786
+ */
+export interface TasksReorderRankParams {
+  /**
+   * Ordered task IDs describing the desired top-to-bottom column order. Each
+   * task's `position` is set to its (1-based) index in this array. All IDs
+   * SHOULD share a sibling scope (same `parentId`); IDs not found are reported
+   * in {@link TasksReorderRankResult.skipped} rather than failing the batch.
+   */
+  orderedIds: string[];
+}
+/**
+ * Result of `tasks.reorder-rank` — within-column rank confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksReorderRankResult {
+  /** Task IDs whose `position` was written, in the new top-to-bottom order. */
+  ranked: string[];
+  /** Task IDs from the request that did not resolve to a task (no-op for these). */
+  skipped: string[];
+  /** Number of tasks re-ranked (= `ranked.length`). */
+  count: number;
+}
+
+/**
+ * Params for `tasks.bulk-move` — atomic status/stage transition for N tasks.
+ *
+ * Moves a set of tasks to a new `status` (and optionally `pipelineStage`) inside
+ * a SINGLE DB transaction — the Kanban "select N cards, drop them in a new
+ * column" shape. Either `status` or `pipelineStage` (or both) MUST be supplied;
+ * an empty target is rejected. All-or-nothing: any failure rolls back every move.
+ *
+ * @task T11786
+ */
+export interface TasksBulkMoveParams {
+  /** Task IDs to move. Non-empty. */
+  taskIds: string[];
+  /** Target lifecycle status applied to every task. */
+  status?: string;
+  /** Target pipeline stage applied to every task (forward-only validation). */
+  pipelineStage?: string;
+}
+/**
+ * Result of `tasks.bulk-move` — atomic multi-move confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksBulkMoveResult {
+  /** Task IDs successfully moved (all-or-nothing — empty only when count is 0). */
+  moved: string[];
+  /** The status applied, when supplied. */
+  status?: string;
+  /** The pipeline stage applied, when supplied. */
+  pipelineStage?: string;
+  /** Number of tasks moved (= `moved.length`). */
+  count: number;
+}
+
+/**
+ * Params for `tasks.assignee` — set/clear a task's first-class assignee.
+ *
+ * A first-class human/owner assignee surface, DISTINCT from the agent
+ * claim/unclaim lock (`tasks.claim` does a conditional atomic claim with
+ * agent-lock semantics; `tasks.assignee` is a direct unconditional set/clear an
+ * operator or Studio board uses). Pass `assignee: null` (or omit it) to clear.
+ *
+ * @task T11786
+ */
+export interface TasksAssigneeParams {
+  /** Task ID whose assignee is being set or cleared. */
+  taskId: string;
+  /**
+   * The assignee to set. `null` / empty / omitted CLEARS the assignee. A
+   * non-empty string assigns the task to that owner.
+   */
+  assignee?: string | null;
+}
+/**
+ * Result of `tasks.assignee` — assignee set/clear confirmation.
+ *
+ * @task T11786
+ */
+export interface TasksAssigneeResult {
+  /** The task ID whose assignee changed. */
+  taskId: string;
+  /** The new assignee value (null when cleared). */
+  assignee: string | null;
+  /** True when an assignee was set; false when it was cleared. */
+  assigned: boolean;
+}
+
 // tasks.relates.add — relatedId is canonical; targetId kept for backward compat (T5149)
 export interface TasksRelatesAddParams {
   taskId: string;
@@ -1469,6 +1576,14 @@ export interface TasksCompleteQueryParams {
    * @saga T10538 (PM-Core V2 agent-trust)
    */
   cancelledChildWaiverReason?: string;
+  /**
+   * Reason for waiving the `E_CLEO_DEPENDENCY` gate when this task's own work
+   * is done but its `depends` edges point at not-yet-terminal tasks (a stale or
+   * over-specified dependency). Recorded to `.cleo/audit/depends-waiver.jsonl`.
+   *
+   * @task T11954 (DHQ-071)
+   */
+  waiveDependsReason?: string;
 }
 /**
  * Result of `tasks.complete` — completion confirmation with unblocked tasks.
@@ -2004,6 +2119,10 @@ export type TasksOps = {
   readonly restore: readonly [TasksRestoreParams, TasksRestoreResult];
   readonly reparent: readonly [TasksReparentQueryParams, TasksReparentDispatchResult];
   readonly reorder: readonly [TasksReorderQueryParams, TasksReorderDispatchResult];
+  // T11786 (epic T11556) — bulk task mutate ops Studio's interactive Kanban binds to.
+  readonly 'reorder-rank': readonly [TasksReorderRankParams, TasksReorderRankResult];
+  readonly 'bulk-move': readonly [TasksBulkMoveParams, TasksBulkMoveResult];
+  readonly assignee: readonly [TasksAssigneeParams, TasksAssigneeResult];
   readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
   readonly 'relates.add-batch': readonly [TasksRelatesAddBatchParams, TasksRelatesAddBatchResult];
   readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];

package/src/operations/validate.ts

@@ -2,11 +2,9 @@
  * Validate / Check Domain Operations
  *
  * T982 extension: Added new types for gate, archive, coherence, compliance-sync,
- * chain, grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
+ * grade, canon, workflow-compliance, verify-explain, and all protocol subtypes.
  */
 
-import type { WarpChain } from '../warp-chain.js';
-
 export type ValidationSeverity = 'error' | 'warning' | 'info';
 
 export interface ValidationViolation {
@@ -242,16 +240,6 @@ export interface ValidateArchiveStatsParams {
 }
 export type ValidateArchiveStatsResult = Record<string, unknown>;
 
-export interface ValidateChainParams {
-  chain: WarpChain;
-}
-export interface ValidateChainResult {
-  wellFormed: boolean;
-  gateSatisfiable: boolean;
-  errors: string[];
-  warnings: string[];
-}
-
 export interface ValidateGradeParams {
   sessionId: string;
 }
@@ -379,7 +367,6 @@ export type CheckOps = {
   readonly 'gate.set': readonly [ValidateGateParams, ValidateGateResult];
   readonly 'verify.explain': readonly [ValidateVerifyExplainParams, ValidateVerifyExplainResult];
   readonly 'archive.stats': readonly [ValidateArchiveStatsParams, ValidateArchiveStatsResult];
-  readonly 'chain.validate': readonly [ValidateChainParams, ValidateChainResult];
   readonly grade: readonly [ValidateGradeParams, ValidateGradeResult];
   readonly 'grade.list': readonly [ValidateGradeListParams, ValidateGradeListResult];
   readonly canon: readonly [ValidateCanonParams, ValidateCanonResult];

package/src/playbook.ts

@@ -58,6 +58,62 @@ export interface PlaybookAgenticNode extends PlaybookNodeBase {
    * Enforced at spawn time by composeSpawnPayload (T1261 PSYCHE E4).
    */
   context_files?: string[];
+  /**
+   * Pin this stage's LLM to a named profile from `llm.profiles` (T11759 · M4).
+   *
+   * When present, the dispatcher resolves the stage's LLM through the E9
+   * chokepoint (`resolveLLMForSystem`) keyed by the cantbook node identity
+   * (`cantbook:<playbook>#<nodeId>`) with this profile name threaded as the
+   * pin — so the named profile's provider/model/credential win over the
+   * background role default. Additive: a node without `profile`/`model`/
+   * `provider` resolves exactly as before.
+   */
+  profile?: string;
+  /**
+   * Pin this stage's LLM to an explicit model id (T11759 · M4).
+   *
+   * A lower-precedence escape hatch than {@link profile}: when no `profile` is
+   * declared the dispatcher threads this model id as the resolution hint. The
+   * runtime never constructs a transport from it — it is a resolution hint
+   * consumed by the Pi runner / model-runner downstream (Gate-13).
+   */
+  model?: string;
+  /**
+   * Pin this stage's LLM to an explicit provider transport (T11759 · M4).
+   *
+   * Paired with {@link model} as the inline escape hatch when no {@link profile}
+   * is declared. A resolution hint only — never used to build a client here.
+   */
+  provider?: string;
+  /**
+   * Per-step skill allowlist enforced at spawn time (T1947 · M4 cantbook
+   * done-gate, Gap E/F).
+   *
+   * When present, the spawned agent's effective skill set is the INTERSECTION
+   * of the agent's resolved skills (the Tier-0/1/2 baseline) and this list — a
+   * skill not in both is dropped. The allowlist can only RESTRICT the baseline,
+   * never expand it: a skill named here that the agent does not already carry is
+   * NOT added. Additive: a node without `allowed_skills` spawns with its full
+   * baseline skill set, exactly as before.
+   *
+   * Enforced by `composeSpawnPayload` (it intersects `resolvedAgent.skills` with
+   * this list). An empty set after intersection is logged as a warning and the
+   * spawn proceeds with no skills.
+   */
+  allowed_skills?: string[];
+  /**
+   * Per-step tool allowlist enforced at spawn time (T1947 · M4 cantbook
+   * done-gate, Gap E/F).
+   *
+   * When present, the spawned agent's effective tool set is the INTERSECTION of
+   * the agent's resolved tool baseline and this list — a tool not in both is
+   * dropped. Like {@link allowed_skills}, this can only RESTRICT the baseline,
+   * never expand it. Additive: a node without `allowed_tools` is unaffected.
+   *
+   * Enforced by `composeSpawnPayload` AFTER the thin-agent guard, so a worker
+   * still cannot acquire a spawn-capable tool it was never granted.
+   */
+  allowed_tools?: string[];
 }
 
 export interface PlaybookDeterministicNode extends PlaybookNodeBase {
@@ -77,6 +133,55 @@ export interface PlaybookApprovalNode extends PlaybookNodeBase {
 
 export type PlaybookNode = PlaybookAgenticNode | PlaybookDeterministicNode | PlaybookApprovalNode;
 
+/**
+ * Declarative, eval-free predicate over the playbook run `context` used to
+ * guard a conditional branch edge (T11806).
+ *
+ * The predicate is intentionally a *pure data* description — never an
+ * arbitrary expression — so the runtime stays deterministic and sandbox-safe.
+ * The named `field` is resolved against the accumulated run context
+ * (`context[field]`) and compared by exactly one of the optional operators
+ * below. When a `PlaybookEdge` carries a `when` predicate, the runtime only
+ * traverses that edge if the predicate evaluates to `true`.
+ *
+ * Exactly one comparison operator (`equals`, `notEquals`, `exists`, `in`, or
+ * `truthy`) should be supplied; the parser enforces this so an ambiguous
+ * predicate is rejected at parse time rather than mis-routing at runtime.
+ *
+ * @example
+ * ```yaml
+ * edges:
+ *   - from: classify
+ *     to: deep-research        # taken when context.needsResearch === true
+ *     when: { field: needsResearch, equals: true }
+ *   - from: classify
+ *     to: skip-research        # taken when context.needsResearch !== true
+ *     when: { field: needsResearch, notEquals: true }
+ * ```
+ *
+ * @task T11806 — cantbook runtime branching
+ */
+export interface PlaybookEdgeCondition {
+  /** Context key whose value the predicate is evaluated against. */
+  field: string;
+  /** Edge is satisfied when `context[field]` strictly equals this value. */
+  equals?: unknown;
+  /** Edge is satisfied when `context[field]` strictly does NOT equal this value. */
+  notEquals?: unknown;
+  /**
+   * When `true`, edge is satisfied iff `field` is present in context;
+   * when `false`, satisfied iff `field` is absent from context.
+   */
+  exists?: boolean;
+  /** Edge is satisfied when `context[field]` is one of these values. */
+  in?: unknown[];
+  /**
+   * When `true`, edge is satisfied iff `context[field]` is truthy;
+   * when `false`, satisfied iff `context[field]` is falsy.
+   */
+  truthy?: boolean;
+}
+
 export interface PlaybookEdge {
   from: string;
   to: string;
@@ -84,6 +189,18 @@ export interface PlaybookEdge {
     requires?: string[];
     ensures?: string[];
   };
+  /**
+   * Optional declarative branch guard (T11806). When present, the edge is
+   * only traversed if the {@link PlaybookEdgeCondition} predicate over the
+   * run `context` is satisfied. Edges without `when` are unconditional.
+   *
+   * A node may have multiple outgoing edges as long as every additional
+   * edge carries a `when` guard — the runtime evaluates them against the
+   * current context and routes to the single satisfied successor. More than
+   * one *unconditional* successor remains a fail-closed error (genuine
+   * ambiguity).
+   */
+  when?: PlaybookEdgeCondition;
 }
 
 export interface PlaybookErrorHandler {

package/src/session.ts

@@ -121,6 +121,17 @@ export interface Session {
   previousSessionId?: string | null;
   /** ID of the session that follows this one. @defaultValue undefined */
   nextSessionId?: string | null;
+  /**
+   * ID of the fork-tree PARENT session that spawned this one (T11639).
+   *
+   * Sourced from `CLEO_PARENT_SESSION_ID` (stamped by the supervisor — T11629).
+   * Distinct from {@link Session.previousSessionId} (the linear resume chain):
+   * `parentSessionId` is the orchestrator→worker spawn edge. NULL/undefined for a
+   * root session with no spawning parent.
+   *
+   * @defaultValue undefined
+   */
+  parentSessionId?: string | null;
   /** Provider-specific agent identifier string. @defaultValue undefined */
   agentIdentifier?: string | null;
   /** ISO 8601 timestamp of when the handoff was consumed. @defaultValue undefined */