@cleocode/contracts 2026.5.101 → 2026.5.103

package/src/dispatch/operations-registry.ts

@@ -2395,6 +2395,39 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'saga.detach',
+    description:
+      'tasks.saga.detach (mutate) — remove a Saga member relation (task_relations type=groups); idempotent; appends to .cleo/audit/saga-detach.jsonl (T10118)',
+    tier: 0,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['sagaId', 'memberId'],
+    params: [
+      {
+        name: 'sagaId',
+        type: 'string',
+        required: true,
+        description: 'Saga task ID',
+        cli: { positional: true },
+      },
+      {
+        name: 'memberId',
+        type: 'string',
+        required: true,
+        description: 'Member task ID to detach from the Saga',
+        cli: { positional: true },
+      },
+      {
+        name: 'reason',
+        type: 'string',
+        required: false,
+        description: 'Human-readable reason recorded in the audit log entry',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'query',
     domain: 'tasks',
@@ -2445,6 +2478,58 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+  {
+    // T10117 — detach I5-violating parentId and re-attach via task_relations
+    // type=groups (ADR-073 §1.2 invariant I5). Idempotent.
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'saga.repair',
+    description:
+      'tasks.saga.repair (mutate) — detach I5-violating parentId and re-attach via task_relations type=groups; idempotent',
+    tier: 0,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: ['sagaId'],
+    params: [
+      {
+        name: 'sagaId',
+        type: 'string',
+        required: true,
+        description: 'Saga task ID (must have label=saga)',
+        cli: { positional: true },
+      },
+    ] satisfies ParamDef[],
+  },
+  {
+    // T10121 — idempotent cron-safe saga auto-close repair. Re-applies
+    // T10116 logic for sagas whose members reached 100% terminal via paths
+    // OTHER than completeTask (bulk SQL, crash recovery, manual edits).
+    // Supersedes T10098 standalone scope.
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'saga.reconcile',
+    description:
+      'tasks.saga.reconcile (mutate) — idempotent cron-safe saga auto-close repair; per-saga advisory lock + audit log; supersedes T10098',
+    tier: 0,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'sagaId',
+        type: 'string',
+        required: false,
+        description: 'Optional saga task ID. Omit to walk every saga.',
+        cli: { positional: true },
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description: 'Report what would happen without mutating rows or writing audit log',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'tasks',

package/src/doctor.ts

@@ -202,6 +202,90 @@ export interface OrphanScanResult {
   softWarnMessage?: string;
 }
 
+// ============================================================================
+// Saga Hierarchy Audit (T10119 — ADR-073 §1.2 invariant + drift detection)
+// ============================================================================
+
+/**
+ * Stable invariant identifiers surfaced by the saga hierarchy audit
+ * (ADR-073 §1.2). `I5` and `I7` mirror the runtime guards in
+ * `packages/core/src/sagas/enforcement.ts`. `depth` covers the I5/I7 depth
+ * ladder (saga → member-Epic → Task → Subtask = 3 hops max). `auto-close-drift`
+ * is a soft-drift detector (no invariant strictly broken — the saga is
+ * structurally valid, but every member is done while the saga still says
+ * pending; T10116 fixes the root cause).
+ */
+export type SagaAuditViolationKind = 'I5' | 'I7' | 'depth' | 'auto-close-drift';
+
+/**
+ * One violation surfaced by {@link auditSagaHierarchy}.
+ *
+ * Each violation is actionable: the `repairCommand` field names the
+ * canonical `cleo` invocation an operator should run to resolve it.
+ */
+export interface SagaAuditViolation {
+  /** Stable violation identifier (`I5`, `I7`, `depth`, `auto-close-drift`). */
+  kind: SagaAuditViolationKind;
+  /** Saga task ID where the violation was detected. */
+  sagaId: string;
+  /**
+   * The offending member task ID. Equal to `sagaId` for I5 violations
+   * (the saga row itself is the offender). For I7 violations, the
+   * nested-saga candidate. For `auto-close-drift`, equal to `sagaId`.
+   */
+  offendingId: string;
+  /** Human-readable message naming both IDs and the repair command. */
+  message: string;
+  /** Canonical `cleo` command an operator should run to resolve. */
+  repairCommand: string;
+}
+
+/**
+ * Per-saga audit summary returned by {@link auditSagaHierarchy}.
+ *
+ * Carries enough context for the doctor CLI to render a one-line summary
+ * (`Saga T#### · status=… · 4/5 members done · 0 violations`) without a
+ * second database round-trip.
+ */
+export interface SagaAuditEntry {
+  /** Saga task ID. */
+  sagaId: string;
+  /** Saga title (for human-readable rendering). */
+  title: string;
+  /** Saga status (`pending`, `active`, `done`, …). */
+  status: string;
+  /** Total member-Epic count. */
+  memberCount: number;
+  /** Member-Epics with `status='done'`. */
+  doneCount: number;
+  /**
+   * Violations attributable to this saga. Always returned (possibly
+   * empty) so callers can render a stable rows-then-violations layout.
+   */
+  violations: SagaAuditViolation[];
+}
+
+/**
+ * Aggregated result returned by {@link auditSagaHierarchy}.
+ *
+ * `count` is the total number of `I5`/`I7`/`depth` invariant violations
+ * across all sagas — the doctor CLI uses this to decide whether to set
+ * a non-zero exit code (`auto-close-drift` is a soft warning and does
+ * NOT alone trigger exit≠0; tests pass with drift but no I-invariant
+ * failure).
+ *
+ * `driftCount` is the number of `auto-close-drift` warnings (kept
+ * separate so CI gates can opt-in to treating drift as failure).
+ */
+export interface SagaAuditResult {
+  /** All sagas audited, sorted by `sagaId` ascending. */
+  sagas: SagaAuditEntry[];
+  /** Total I5/I7/depth invariant violations across all sagas. */
+  count: number;
+  /** Total auto-close-drift warnings across all sagas. */
+  driftCount: number;
+}
+
 /**
  * One line appended to `.cleo/audit/worktree-prune.jsonl` per prune
  * operation. Extends the existing audit-log schema (timestamp +

package/src/errors.ts

@@ -233,6 +233,67 @@ export class LeadBypassDetectedError extends Error {
   }
 }
 
+/**
+ * LAFS error code emitted when a saga-labeled epic carries forbidden parent or
+ * `depends` edges — ADR-073 §1.2 invariant **I3** violation.
+ *
+ * Sagas MUST link to member Epics exclusively via
+ * `task_relations.type='groups'`; a parent or depends edge re-introduces the
+ * depth-budget consumption the saga tier was created to avoid.
+ *
+ * Runtime guard: `assertSagaInvariantI3` (in `@cleocode/core` saga module).
+ *
+ * @task T10115
+ * @saga T10113
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+export const E_SAGA_INVARIANT_VIOLATION_I3 = 'E_SAGA_INVARIANT_VIOLATION_I3' as const;
+
+/**
+ * LAFS error code emitted when a saga-labeled row has a non-null `parentId` —
+ * ADR-073 §1.2 invariant **I5** violation.
+ *
+ * Sagas are top-level groupings; they do not nest under any task. A non-null
+ * `parentId` on a saga-labeled row indicates storage corruption or a faulty
+ * import path.
+ *
+ * Runtime guard: `assertSagaInvariantI5` (in `@cleocode/core` saga module).
+ *
+ * @task T10115
+ * @saga T10113
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+export const E_SAGA_INVARIANT_VIOLATION_I5 = 'E_SAGA_INVARIANT_VIOLATION_I5' as const;
+
+/**
+ * LAFS error code emitted when a saga-member candidate is itself a saga —
+ * ADR-073 §1.2 invariant **I7** violation (no nested sagas).
+ *
+ * Nested sagas would re-introduce the multi-release grouping depth the tier
+ * was created to flatten.
+ *
+ * Runtime guard: `assertSagaInvariantI7` (in `@cleocode/core` saga module).
+ *
+ * @task T10115
+ * @saga T10113
+ * @see ADR-073-above-epic-naming.md §1.2
+ */
+export const E_SAGA_INVARIANT_VIOLATION_I7 = 'E_SAGA_INVARIANT_VIOLATION_I7' as const;
+
+/**
+ * Union of saga-invariant LAFS error codes (I3 / I5 / I7).
+ *
+ * Useful for narrowing thrown error codes from
+ * `assertSagaInvariantI{3,5,7}` in dispatch handlers.
+ *
+ * @task T10115
+ * @saga T10113
+ */
+export type SagaInvariantErrorCode =
+  | typeof E_SAGA_INVARIANT_VIOLATION_I3
+  | typeof E_SAGA_INVARIANT_VIOLATION_I5
+  | typeof E_SAGA_INVARIANT_VIOLATION_I7;
+
 /**
  * Normalize any thrown value into a standardized error object.
  *

package/src/index.ts

@@ -128,6 +128,16 @@ export type {
   BackupMetadata,
   BackupScope,
 } from './backup-manifest.js';
+// === Boundary Registry (SSoT for Rust/TS layering — ADR-078, Saga T10176) ===
+export type {
+  BoundaryEntry,
+  CanonicalHome,
+  PerfBudget,
+  SafetyBudget,
+  ThroughputThreshold,
+  WorkloadIntent,
+} from './boundary.js';
+export { BOUNDARY_REGISTRY } from './boundary.js';
 // === Brain/Memory Types ===
 export type {
   BrainCognitiveType,
@@ -302,12 +312,17 @@ export {
   DocKindRegistry,
 } from './docs-taxonomy.js';
 // === Doctor: Worktree-Orphan Audit + Prune Types (T9790, T9808, T9962) ===
+// === Doctor: Saga Hierarchy Audit (T10119 — ADR-073 §1.2) ===
 export type {
   ComprehensiveAuditResult,
   OrphanEntry,
   OrphanScanResult,
   PruneAuditEntry,
   PruneResult,
+  SagaAuditEntry,
+  SagaAuditResult,
+  SagaAuditViolation,
+  SagaAuditViolationKind,
   WorktreeAnomaly,
   WorktreeAnomalyKind,
 } from './doctor.js';
@@ -334,12 +349,16 @@ export {
   TASK_SEVERITIES,
   TASK_SIZES,
 } from './enums.js';
+export type { SagaInvariantErrorCode } from './errors.js';
 // === Error Utilities ===
 export {
   ClassifierUnregisteredAgentError,
   createErrorResult,
   createSuccessResult,
   DecisionValidatorFailedError,
+  E_SAGA_INVARIANT_VIOLATION_I3,
+  E_SAGA_INVARIANT_VIOLATION_I5,
+  E_SAGA_INVARIANT_VIOLATION_I7,
   formatError,
   getErrorMessage,
   isErrorResult,
@@ -1156,6 +1175,8 @@ export type {
   TasksSagaAddResult,
   TasksSagaCreateParams,
   TasksSagaCreateResult,
+  TasksSagaDetachParams,
+  TasksSagaDetachResult,
   TasksSagaListParams,
   TasksSagaListResult,
   TasksSagaMembersParams,

package/src/operations/tasks.ts

@@ -1048,19 +1048,75 @@ export interface TasksSagaAddResult {
   added: boolean;
 }
 
+/**
+ * Params for `tasks.saga.detach` — remove a Saga member relation
+ * (`task_relations.type='groups'`). Idempotent.
+ *
+ * @task T10118
+ * @see ADR-073-above-epic-naming.md §1.2 invariant I7
+ */
+export interface TasksSagaDetachParams {
+  /** Saga task ID (the `from` side of the groups relation). */
+  sagaId: string;
+  /** Member task ID (the `to` side of the groups relation). */
+  memberId: string;
+  /** Optional human-readable reason recorded in the audit log entry. */
+  reason?: string;
+}
+
+/**
+ * Result of `tasks.saga.detach` — relation removal confirmation + audit
+ * record (always appended even on idempotent no-op).
+ *
+ * @task T10118
+ */
+export interface TasksSagaDetachResult {
+  /** Saga task ID. */
+  sagaId: string;
+  /** Member task ID that was detached. */
+  memberId: string;
+  /** True when a row was actually removed; false on idempotent no-op. */
+  removed: boolean;
+  /** Reason recorded in the audit log entry. */
+  reason: string;
+  /** ISO 8601 timestamp recorded in the audit log entry. */
+  timestamp: string;
+}
+
 /** Params for `tasks.saga.list` — list all Sagas. */
 export type TasksSagaListParams = Record<string, never>;
 
+/**
+ * A single I5-violation warning entry returned by `tasks.saga.list` when a
+ * saga row carries a non-null `parentId` (ADR-073 §1.2 invariant I5).
+ *
+ * @task T10117
+ */
+export interface TasksSagaInvariantI5Warning {
+  /** Fixed warning code. */
+  code: 'E_SAGA_INVARIANT_VIOLATION_I5';
+  /** Saga task ID whose `parentId` violates invariant I5. */
+  sagaId: string;
+  /** The non-null `parentId` value found on the saga row. */
+  offendingParentId: string;
+}
+
 /**
  * Result of `tasks.saga.list` — all labeled top-level Epics.
  *
  * @task T9521
+ * @task T10117 — added optional `warnings` array for I5 violations
  */
 export interface TasksSagaListResult {
   /** Array of Saga task records. */
   sagas: TaskRecord[];
   /** Total count. */
   total: number;
+  /**
+   * One entry per saga with a non-null `parentId`. Omitted entirely when no
+   * violations were observed (pre-T10117 envelope shape preserved).
+   */
+  warnings?: TasksSagaInvariantI5Warning[];
 }
 
 /** Params for `tasks.saga.members` — list member Epics linked to a Saga. */
@@ -1083,6 +1139,124 @@ export interface TasksSagaMembersResult {
   total: number;
 }
 
+/**
+ * Params for `tasks.saga.repair` — detach an I5-violating `parentId` from a
+ * Saga and re-attach via `task_relations.type='groups'`.
+ *
+ * @task T10117
+ * @see ADR-073-above-epic-naming.md §1.2 — invariant I5
+ */
+export interface TasksSagaRepairParams {
+  /** Saga task ID (must have `label='saga'`). */
+  sagaId: string;
+}
+
+/**
+ * Result of `tasks.saga.repair` — idempotent detach + re-attach.
+ *
+ * @task T10117
+ */
+export interface TasksSagaRepairResult {
+  /** Saga task ID that was inspected. */
+  sagaId: string;
+  /** `true` when the call performed a state change; `false` for no-op. */
+  repaired: boolean;
+  /** The detached `parentId` value, or `null` when no detach was needed. */
+  detachedParentId: string | null;
+  /**
+   * The `groups` edge that was written, or `null` for the idempotent no-op
+   * and the missing-former-parent edge case.
+   */
+  attachedRelation: {
+    from: string;
+    to: string;
+    type: 'groups';
+  } | null;
+  /** Free-form notes the CLI renderer can surface alongside the result. */
+  note?: string;
+}
+
+/**
+ * Per-saga reconciliation action returned by `tasks.saga.reconcile`.
+ *
+ * @task T10121
+ */
+export type TasksSagaReconcileAction = 'close' | 'no-op' | 'blocked' | 'error';
+
+/**
+ * Params for `tasks.saga.reconcile` — idempotent cron-safe saga auto-close
+ * repair. Re-applies the T10116 auto-close logic for sagas whose members
+ * reached 100% terminal status via paths OTHER than `completeTask` (bulk
+ * SQL repair, crash recovery, manual state edits).
+ *
+ * @task T10121
+ * @see ADR-073-above-epic-naming.md §1.3
+ */
+export interface TasksSagaReconcileParams {
+  /**
+   * Optional single saga to reconcile. When omitted, the verb walks every
+   * saga returned by `taskList({ type: 'epic', label: 'saga' })`.
+   */
+  sagaId?: string;
+  /**
+   * When `true`, run in report-only mode — log what would happen without
+   * mutating any rows or writing to the audit log.
+   */
+  dryRun?: boolean;
+}
+
+/**
+ * Per-saga reconciliation outcome surfaced inside
+ * {@link TasksSagaReconcileResult}.
+ *
+ * @task T10121
+ */
+export interface TasksSagaReconcileEntry {
+  /** Saga task ID this entry refers to. */
+  sagaId: string;
+  /** The action the reconciler took for this saga. */
+  action: TasksSagaReconcileAction;
+  /** Member task IDs considered by the closure check. */
+  members: string[];
+  /** Members that satisfied the terminal-status predicate. */
+  terminalMembers: string[];
+  /** Members that did NOT satisfy the terminal-status predicate. */
+  pendingMembers: string[];
+  /** Saga status BEFORE this run. */
+  statusBefore: string;
+  /** Saga status AFTER this run (== `statusBefore` for no-op/blocked/error). */
+  statusAfter: string;
+  /** Free-form human-readable reason recorded for the audit entry. */
+  reason: string;
+  /** ISO 8601 timestamp the decision was recorded. */
+  timestamp: string;
+}
+
+/**
+ * Result of `tasks.saga.reconcile` — aggregate counters + per-saga entries
+ * in stable id order.
+ *
+ * @task T10121
+ */
+export interface TasksSagaReconcileResult {
+  /** Total number of sagas inspected (== `entries.length`). */
+  total: number;
+  /** Number of sagas the run flipped to `status='done'`. */
+  closed: number;
+  /** Number of sagas already in the correct terminal state. */
+  noOp: number;
+  /** Number of sagas blocked behind a concurrent lock holder. */
+  blocked: number;
+  /** Number of sagas with pending non-terminal members (not closed). */
+  pending: number;
+  /** Number of sagas that errored out during reconciliation. */
+  errors: number;
+  /** Whether this run ran in dry-run mode. */
+  dryRun: boolean;
+  /** Detailed per-saga entries in stable id order. */
+  entries: TasksSagaReconcileEntry[];
+}
+
 /** Params for `tasks.saga.rollup` — aggregate member Epic statuses. */
 export interface TasksSagaRollupParams {
   /** Saga task ID. */
@@ -1169,7 +1343,12 @@ export type TasksOps = {
   // Saga sub-domain ops (ADR-073)
   readonly 'saga.create': readonly [TasksSagaCreateParams, TasksSagaCreateResult];
   readonly 'saga.add': readonly [TasksSagaAddParams, TasksSagaAddResult];
+  readonly 'saga.detach': readonly [TasksSagaDetachParams, TasksSagaDetachResult];
   readonly 'saga.list': readonly [TasksSagaListParams, TasksSagaListResult];
   readonly 'saga.members': readonly [TasksSagaMembersParams, TasksSagaMembersResult];
   readonly 'saga.rollup': readonly [TasksSagaRollupParams, TasksSagaRollupResult];
+  /** T10117 — repair an I5-violating saga. */
+  readonly 'saga.repair': readonly [TasksSagaRepairParams, TasksSagaRepairResult];
+  /** T10121 — idempotent cron-safe auto-close repair (supersedes T10098 scope). */
+  readonly 'saga.reconcile': readonly [TasksSagaReconcileParams, TasksSagaReconcileResult];
 };

package/src/operations/worktree.ts

@@ -449,8 +449,38 @@ export interface WorktreeInfo {
   owningAgent: string | null;
   /** ISO-8601 timestamp of last activity (newest commit OR mtime of working tree). */
   lastActivity: string;
+  /**
+   * ISO-8601 timestamp recording when this worktree was first created.
+   *
+   * Resolution order:
+   *  1. For git-native entries — mtime of the per-worktree admin file
+   *     `<gitCommonDir>/worktrees/<basename(path)>/HEAD`. Git writes this once
+   *     at `git worktree add` time and never rewrites it during normal usage,
+   *     making it a faithful proxy for creation time.
+   *  2. For sentinel-only entries — the `adoptedAt` timestamp persisted in
+   *     `.cleo/worktrees.json`.
+   *  3. Fallback — mtime of the worktree directory itself.
+   *
+   * Distinct from {@link lastActivity}, which moves with each new commit on
+   * the branch. The two values diverge for any worktree that has had at least
+   * one commit since creation.
+   *
+   * @task T9546
+   */
+  createdAt: string;
   /** Whether `git worktree list --porcelain` reports the worktree as locked. */
   isLocked: boolean;
+  /**
+   * Lock-state string mirroring {@link isLocked} as a discriminated literal.
+   *
+   * Provided for downstream consumers that want a single human-readable token
+   * rather than a boolean — `'locked'` when porcelain reports the worktree as
+   * locked, `'unlocked'` otherwise. Always equivalent to
+   * `isLocked ? 'locked' : 'unlocked'`.
+   *
+   * @task T9546
+   */
+  lockState: 'locked' | 'unlocked';
   /** Whether the worktree is stale: no activity > N days AND (task done/cancelled OR branch merged). */
   isStale: boolean;
   /** Whether the branch is reachable from `main` (already integrated). */