@cleocode/contracts 2026.6.13 → 2026.6.15

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/worktree.ts

@@ -381,10 +381,20 @@ export interface PruneWorktreesResult {
   removed: number;
   /** Absolute paths that were removed. */
   removedPaths: string[];
+  /** Number of worktrees quarantined (dirty/unpushed — preserved, not deleted). */
+  quarantined: number;
+  /** Absolute paths of quarantined worktrees. */
+  quarantinedPaths: string[];
   /** Entries that failed to remove (with reasons). */
   errors: Array<{ path: string; reason: string }>;
   /** Whether `git worktree prune` was run. */
   gitPruneRan: boolean;
+  /**
+   * True when pruning was skipped entirely because the preserve set was empty
+   * or the task store was unreadable while worktrees exist (fail-closed guard,
+   * T11996). A structured audit warning is written to the lifecycle log.
+   */
+  skippedFailClosed?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -576,6 +586,7 @@ export type WorktreeLifecycleAction =
   | 'adopt'
   | 'prune'
   | 'prune-skip'
+  | 'quarantine'
   | 'force-unlock'
   | 'complete'
   | 'complete-skip'

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 {

package/src/spawn.ts

@@ -4,8 +4,79 @@
  * @task T5240
  * @task T9214 — orchestrator-defer waiver field (W4 UX hardening)
  * @task T9215 — DelegateTaskEnvelope discriminated-union type (W1 wiring)
+ * @task T11998 — per-session suite containment (AgentSuiteOwnership)
  */
 
+// =============================================================================
+// Agent suite ownership handle (T11998 — suite containment)
+// =============================================================================
+
+/**
+ * Containment mode used when spawning an agent process tree.
+ *
+ * - `'systemd'` — the agent and its MCP children run inside a transient
+ *   `systemd --user` scope unit.  The scope is the kill handle.
+ * - `'pgid'` — the agent runs in its own POSIX process group.  Negative-PID
+ *   kill (`kill(-pgid, SIGTERM)`) reaps the whole group.
+ * - `'none'` — no containment (detached+unref legacy path).  The janitor
+ *   (T11995) is the only backstop.
+ */
+export type AgentContainmentMode = 'systemd' | 'pgid' | 'none';
+
+/**
+ * Ownership/cleanup handle recorded per spawned agent session.
+ *
+ * This record is stored alongside the {@link SpawnResult} so that
+ * `terminate()` and session-end flows can reap the entire process tree
+ * (including indirectly-spawned MCP grandchildren) via a single kill.
+ *
+ * ## Systemd path
+ * `systemctl --user stop <unitName>` stops the scope and all processes
+ * inside it.  If the scope has already exited, use `reset-failed` to clear
+ * the failed-unit ledger; ESRCH / no-such-unit errors are no-ops.
+ *
+ * ## Pgid path
+ * `process.kill(-pgid, 'SIGTERM')` sends SIGTERM to every process in the
+ * group.  After a grace period, `process.kill(-pgid, 'SIGKILL')` cleans
+ * up survivors.  ESRCH is a no-op (group already gone).
+ *
+ * @task T11998
+ */
+export interface AgentSuiteOwnership {
+  /**
+   * Containment mode in effect for this agent spawn.
+   *
+   * Determines which reap primitive to use on session end.
+   */
+  readonly mode: AgentContainmentMode;
+
+  /**
+   * Systemd transient scope unit name (e.g. `cleo-agent-session-T1234.scope`).
+   *
+   * Present only when `mode === 'systemd'`.  Use as the argument to
+   * `systemctl --user stop <unitName>`.
+   */
+  readonly unitName?: string;
+
+  /**
+   * POSIX process-group ID of the spawned agent root process.
+   *
+   * Present only when `mode === 'pgid'`.  Use as negative-PID with kill:
+   * `process.kill(-pgid, 'SIGTERM')`.
+   *
+   * When `mode === 'systemd'` the pgid is also populated as a fallback
+   * handle (e.g. if the scope unit is unavailable at reap time).
+   */
+  readonly pgid?: number;
+
+  /**
+   * PID of the direct child process spawned by cleo.
+   *
+   * Informational — prefer `unitName` or `pgid` for reaping.
+   */
+  readonly pid?: number;
+}
+
 export interface AdapterSpawnProvider {
   canSpawn(): Promise<boolean>;
   spawn(context: SpawnContext): Promise<SpawnResult>;
@@ -48,6 +119,14 @@ export interface SpawnResult {
   endTime?: string;
   /** Error message when status is 'failed'. Contains details about what went wrong. */
   error?: string;
+  /**
+   * Suite containment ownership handle (T11998).
+   *
+   * Present when the spawn provider recorded containment info.
+   * Use this to reap the entire MCP suite tree on session end or terminate().
+   * Absent for legacy spawns that used detached+unref without containment.
+   */
+  ownership?: AgentSuiteOwnership;
 }
 
 // =============================================================================