@cleocode/contracts 2026.9.22 → 2026.9.24

package/src/operations/tasks.ts

@@ -25,8 +25,13 @@ import type { TaskAnalysisResult, TaskRef } from '../results.js';
  * Common task types (API contract — matches CLI src/types/task.ts)
  */
 import type { TaskStatus } from '../status-registry.js';
-import type { TaskKind, TaskPriority, TaskSeverity, TaskType } from '../task.js';
-import type { MinimalTaskRecord, TaskMatch, TaskRecord } from '../task-record.js';
+import type { TaskClaim, TaskKind, TaskPriority, TaskSeverity, TaskType } from '../task.js';
+import type {
+  MinimalTaskRecord,
+  RecordProjectionDisclosure,
+  TaskMatch,
+  TaskRecord,
+} from '../task-record.js';
 import type { ExternalTask, ExternalTaskLink, ReconcileResult } from '../task-sync.js';
 import type {
   CompletionEvaluateParams,
@@ -285,10 +290,16 @@ export interface TaskShowRelationsEntry {
  * Result of `tasks.show` — the full task record plus its canonical view
  * projection. `view` is null when the task has no lifecycle pipeline.
  *
+ * The inherited `_withheld` marker is set by the default (MVI) projection
+ * when it withholds a field from every `acRows` element: the key
+ * `acRows/*\/id` names the row UUIDs and its value is their UTF-8 byte total
+ * (T12523). `--full` returns the rows unprojected, with no marker.
+ *
  * @task T1703
  * @task T9966 — attachments[] always present (empty array when none)
+ * @task T12523 — `_withheld` for the projected `acRows`
  */
-export interface TasksShowResult {
+export interface TasksShowResult extends RecordProjectionDisclosure {
   /** Full task record (string-widened for dispatch layer serialization). */
   task: TaskRecord;
   /** Canonical task view projection produced by `computeTaskView`. Null when unavailable. */
@@ -307,6 +318,8 @@ export interface TasksShowResult {
    * Acceptance-criterion rows hydrated from the `task_acceptance_criteria`
    * table (T10502). Each entry carries the stable UUID `id`, the
    * `AC<ordinal>` alias, the ordinal itself, and the canonical AC text.
+   * The default (MVI) projection withholds `id` and says so in this result's
+   * `_withheld` (`acRows/*\/id`); `--full` returns it (T12523).
    *
    * Optional — undefined when the task has no rows in the table (e.g.
    * legacy tasks not yet backfilled by T10505). Consumers should fall
@@ -329,8 +342,14 @@ export interface TasksShowResult {
  * @task T10508
  */
 export interface TaskShowAcRowEntry {
-  /** UUIDv4 stable identifier, immutable for the AC's lifetime. */
-  id: string;
+  /**
+   * UUIDv4 stable identifier, immutable for the AC's lifetime.
+   *
+   * Absent under the default (MVI) projection, which cites a criterion by its
+   * `alias` and lists `acRows/*\/id` in the result's `_withheld`; present with
+   * `--full` or a `--field /data/acRows/<i>/id` pointer (T12523).
+   */
+  id?: string;
   /** Display alias derived from ordinal — `AC1`, `AC2`, etc. */
   alias: string;
   /** 1-based ordinal — never reused per task (gaps remain on shrink). */
@@ -921,6 +940,31 @@ export interface TasksComplexityEstimateResult {
 export interface TasksHistoryParams {
   taskId?: string;
   limit?: number;
+  /**
+   * With `taskId`: only ranking-input changes (priority, severity, kind,
+   * depends) — who, which session, why, before/after (T12693, D11161).
+   */
+  ranking?: boolean;
+}
+
+// tasks.ranking.revert
+/** Parameters for `tasks.ranking.revert` (T12693, D11161). */
+export interface TasksRankingRevertParams {
+  /** The `ranking_changed` audit row id to undo (from `cleo history ranking`). */
+  entryId: string;
+  /** Why it is reverted; recorded on the new audit row. */
+  reason?: string;
+  /** Revert even though a field changed again since. */
+  force?: boolean;
+}
+/** Result of `tasks.ranking.revert`. */
+export interface TasksRankingRevertResult {
+  /** Task whose ranking inputs were restored. */
+  taskId: string;
+  /** Fields set back. */
+  fields: string[];
+  /** The values they were set back to. */
+  revertedTo: Record<string, unknown>;
 }
 /**
  * Result of `tasks.history` — audit log entries for a task.
@@ -1655,6 +1699,13 @@ export interface TasksCompleteQueryParams {
    * @task T11954 (DHQ-071)
    */
   waiveDependsReason?: string;
+  /**
+   * Optimistic-concurrency guard (`--if-match`): the task `updatedAt` the
+   * caller read. When the stored version differs, completion fails with
+   * `E_CONFLICT` carrying the current version and the changed fields.
+   * @task T12503
+   */
+  expectedUpdatedAt?: string;
 }
 /**
  * Result of `tasks.complete` — completion confirmation with unblocked tasks.
@@ -1799,51 +1850,91 @@ export interface TasksArchiveQueryResult {
   archivedTasks: Array<{ id: string }>;
 }
 
-// tasks.claim
+/**
+ * Params for `tasks.claim` — take, renew or override the caller session's
+ * leased claim on a task (T12502). The human `assignee` is never written.
+ *
+ * @task T1703
+ * @task T12502
+ */
 export interface TasksClaimParams {
+  /** Task to claim. */
   taskId: string;
-  agentId: string;
+  /** Agent identity recorded with the lease; defaults to the session's agent / `CLEO_AGENT_ID`. */
+  agentId?: string;
+  /** Renew the caller's own lease instead of taking one (`--renew`). */
+  renew?: boolean;
+  /** Take over an EXPIRED lease held by another session (`--take-over`, audited). */
+  takeOver?: boolean;
+  /** Take over a LIVE lease held by another session (`--force-claim`, audited). */
+  forceClaim?: boolean;
 }
 /**
- * Result of `tasks.claim` — agent claim confirmation.
+ * Result of `tasks.claim` — the lease now held.
  *
  * @task T1703
+ * @task T12502
  */
 export interface TasksClaimResult {
   /** The task ID that was claimed. */
   taskId: string;
-  /** The agent ID that now holds the claim. */
-  agentId: string;
+  /** The agent ID recorded with the lease, or `null`. */
+  agentId: string | null;
+  /** The lease held by the caller's session. */
+  claim: TaskClaim;
 }
 
-// tasks.unclaim
+/**
+ * Params for `tasks.unclaim` — release the caller session's lease (T12502).
+ *
+ * @task T12502
+ */
 export interface TasksUnclaimParams {
+  /** Task to release. */
   taskId: string;
+  /** Release a lease held by ANOTHER session (`--force-claim`, audited). */
+  forceClaim?: boolean;
 }
 /**
  * Result of `tasks.unclaim` — agent release confirmation.
  *
  * @task T1703
+ * @task T12502
  */
 export interface TasksUnclaimResult {
   /** The task ID whose claim was released. */
   taskId: string;
+  /** `true` when a lease was cleared; `false` when the task was unclaimed. */
+  released: boolean;
 }
 
-// tasks.start (dispatch-level)
+/**
+ * Params for `tasks.start`. T12502: the start takes the caller session's
+ * claim lease; the flags are the explicit, audited overrides.
+ *
+ * @task T12502
+ */
 export interface TasksStartQueryParams {
+  /** Task to start. */
   taskId: string;
+  /** Take over an EXPIRED lease held by another session (`--take-over`). */
+  takeOver?: boolean;
+  /** Take over a LIVE lease held by another session (`--force-claim`). */
+  forceClaim?: boolean;
 }
 /**
  * Result of `tasks.start` — work-start confirmation.
  *
  * @task T1703
+ * @task T12502
  */
 export interface TasksStartQueryResult {
   /** The task ID that is now active. */
   taskId: string;
   /** The task ID that was previously active (auto-stopped), or null. */
   previousTask: string | null;
+  /** The claim lease this start holds, or `null` for an unbound caller (no lease). */
+  claim?: TaskClaim | null;
 }
 
 // tasks.stop (dispatch-level)
@@ -2277,6 +2368,7 @@ export type TasksOps = {
   readonly 'relates.add': readonly [TasksRelatesAddParams, TasksRelatesAddResult];
   readonly 'relates.add-batch': readonly [TasksRelatesAddBatchParams, TasksRelatesAddBatchResult];
   readonly 'relates.remove': readonly [TasksRelatesRemoveParams, TasksRelatesRemoveResult];
+  readonly 'ranking.revert': readonly [TasksRankingRevertParams, TasksRankingRevertResult];
   readonly start: readonly [TasksStartQueryParams, TasksStartQueryResult];
   readonly stop: readonly [TasksStopQueryParams, TasksStopQueryResult];
   readonly 'sync.reconcile': readonly [TasksSyncReconcileParams, TasksSyncReconcileResult];

package/src/project-lifecycle.ts

@@ -124,8 +124,12 @@ export interface RerootProjectResult {
   checkpointPath: string;
   /** Top-level entries renamed from the old root into the new one. */
   renamed: string[];
-  /** Whether `.cleo/project-id` was already present or had to be written. */
-  projectIdFile: 'present' | 'written';
+  /**
+   * Whether the tracked identity was already present (`.cleo/project.json`),
+   * present only as the legacy `.cleo/project-id` (`legacy`, T12716), or had
+   * to be written.
+   */
+  projectIdFile: 'present' | 'written' | 'legacy';
   /** Absolute path of the tombstone left at the old root. */
   tombstone: string;
   /** Registry status after the rebind. */

package/src/session.ts

@@ -132,6 +132,17 @@ export interface Session {
    * @defaultValue undefined
    */
   parentSessionId?: string | null;
+  /**
+   * ID of the orchestrator session that SPAWNED this one, recorded by the
+   * spawn itself (T12502). Unlike {@link Session.parentSessionId}, which a
+   * process declares for itself at `session start`, only the spawn writes
+   * this edge, so the task-claim chokepoint trusts it to let a spawn family
+   * pass a live lease between its members. Read-only on the session record:
+   * the whole-row session upsert never writes it.
+   *
+   * @defaultValue undefined
+   */
+  spawnedBySessionId?: string | null;
   /** Provider-specific agent identifier string. @defaultValue undefined */
   agentIdentifier?: string | null;
   /** ISO 8601 timestamp of when the handoff was consumed. @defaultValue undefined */
@@ -233,9 +244,16 @@ export class SessionView {
     return this._sessions.length;
   }
 
-  /** Find the currently active session (if any). */
+  /**
+   * First `active` session in THIS collection — a scan over the rows the
+   * caller loaded, NOT the caller's own session (T12500). With several agents
+   * active it names an arbitrary one of them.
+   *
+   * @deprecated For "my session" use `resolveBoundSession` (mutations) or
+   *   `resolveSessionForRead` (reads, labels an unbound guess).
+   */
   findActive(): Session | undefined {
-    return this._sessions.find((s) => s.status === 'active');
+    return this._sessions.find((s) => s.status === 'active'); // get-active-session-allowed: collection scan over caller-supplied rows, not identity (T12500)
   }
 
   /** Find a session by ID. */

package/src/task.ts

@@ -187,6 +187,14 @@ export interface CriterionEvidenceLink {
   artifactPaths: string[];
   /** Indices of actual validated result atoms in the containing gate's atoms array. */
   resultAtomIndices: number[];
+  /**
+   * How the `implemented` link is supported (T12689): `files` when a path the
+   * criterion names is among the inspected artifacts; `self-attested` when the
+   * criterion names no path in them, so the link rests on the agent's claim.
+   * Paths parsed from criterion text are advisory (T12118), so this flags
+   * rather than refuses. Absent on other gates and on older receipts.
+   */
+  basis?: 'files' | 'self-attested';
 }
 
 /** Verification failure log entry. */
@@ -390,6 +398,12 @@ export type EvidenceAtom =
        * (T12671): the task is linked through it and its files are the change.
        */
       componentPrNumber?: number;
+      /**
+       * Paths the (component) PR deleted that stay deleted in the landing
+       * commit (T12689). A deletion has no bytes to hash, so a PR whose every
+       * change is a deletion implements with `pr:` + `note:` instead of `files:`.
+       */
+      deletedPaths?: string[];
     }
   | {
       /**
@@ -709,9 +723,22 @@ export interface Task {
    */
   pipelineStage?: string | null;
 
-  /** Agent ID that has claimed/is assigned to this task. Null when unclaimed. @defaultValue undefined */
+  /**
+   * First-class human / owner assignee (`cleo assignee`, Studio boards).
+   * Separate from the agent work lease in {@link Task.claim}: `cleo start`,
+   * `cleo claim` and spawn never write it (T12502). @defaultValue undefined
+   */
   assignee?: string | null;
 
+  /**
+   * The agent work lease held on this task, when one is recorded (T12502).
+   * Absent when the task is unclaimed. Distinct from the human
+   * {@link Task.assignee}. Read-only on the task object: full-row writes
+   * never carry it, only the claim chokepoint changes it.
+   * @defaultValue undefined
+   */
+  claim?: TaskClaim;
+
   /**
    * Abort reason when a worker was stopped due to runaway detection (T1658).
    *
@@ -1006,3 +1033,26 @@ export interface TaskWorkState {
   /** ID of the primary session managing this work state. @defaultValue undefined */
   primarySession?: string | null;
 }
+
+/**
+ * A leased agent claim on a task (T12502 · epic T12497).
+ *
+ * Taken by `cleo start`, `cleo claim` and spawn with a compare-and-set in the
+ * same write transaction; renewed by the holder session's activity or
+ * `cleo claim <id> --renew`; released by `cleo stop`, completion,
+ * cancellation, archive and the holder session ending. A claim whose
+ * `leaseExpiresAt` has passed stays recorded until another session takes it
+ * over explicitly (`--take-over`, audited).
+ *
+ * @task T12502
+ */
+export interface TaskClaim {
+  /** Session holding the lease. */
+  sessionId: string;
+  /** Agent identity of the holder (`CLEO_AGENT_ID` / spawn handle), or `null`. */
+  agentId: string | null;
+  /** ISO-8601 UTC instant the lease was taken. */
+  claimedAt: string;
+  /** ISO-8601 UTC instant the lease lapses unless renewed. */
+  leaseExpiresAt: string;
+}

package/src/tools/index.ts

@@ -63,6 +63,7 @@ export type {
   ScoreFactor,
   ScoreTaskContext,
   ScoreTaskInput,
+  ScoreTaskKey,
   ScoreTaskResult,
 } from './score-task-priority.js';
 // === Web + browser agent tools (T1742 / T11456) ===

package/src/tools/score-task-priority.ts

@@ -6,7 +6,7 @@
  * @epic T9835
  */
 
-import type { TaskPriority } from '../task.js';
+import type { TaskKind, TaskPriority, TaskSeverity } from '../task.js';
 
 /** Minimal task shape required by scoreTask. */
 export interface ScoreTaskInput {
@@ -24,6 +24,10 @@ export interface ScoreTaskInput {
   createdAt?: string;
   /** Labels for pattern matching. */
   labels?: string[];
+  /** Severity axis (orthogonal to priority); unset for most tasks. */
+  severity?: TaskSeverity | null;
+  /** Kind axis; not part of the order — an unset severity is unknown, never imputed from `kind` (D11161). */
+  kind?: TaskKind | null;
 }
 
 /** Context provided to scoreTask to enable phase-aware and dependency-aware scoring. */
@@ -38,6 +42,8 @@ export interface ScoreTaskContext {
   successPatterns?: Array<{ pattern: string }>;
   /** Matched failure patterns from BRAIN (optional penalty scoring). */
   failurePatterns?: Array<{ pattern: string }>;
+  /** Open tasks that depend on each task id — its leverage (bounded bonus, T12661). */
+  leverage?: ReadonlyMap<string, number>;
 }
 
 /** A scoring factor contributing to the final score. */
@@ -48,12 +54,32 @@ export interface ScoreFactor {
   delta: number;
   /** Human-readable explanation. */
   detail: string;
+  /**
+   * Comparator tier the factor belongs to (T12691): 1 priority band, 2 severity,
+   * 3 bounded tiebreak; `null` for an informational factor outside the order.
+   */
+  tier?: 1 | 2 | 3 | null;
+}
+
+/** The lexicographic sort key of a scored task (T12691); higher sorts first. */
+export interface ScoreTaskKey {
+  /** Owner priority band: critical 4, high 3, medium 2, low 1. */
+  band: number;
+  /** Attested severity: P0 4, P1 3, P2 2, P3 1, unknown 0. */
+  severity: number;
+  /** Bounded computed tiebreak (deps, phase, leverage, age). */
+  tiebreak: number;
 }
 
 /** Result of scoreTask. */
 export interface ScoreTaskResult {
-  /** Final computed score. */
+  /**
+   * The key as one number that sorts identically (band × 10000 + severity ×
+   * 1000 + tiebreak), for display and single-number consumers.
+   */
   score: number;
-  /** Individual scoring factors. */
+  /** Individual scoring factors, each tagged with its comparator tier. */
   factors: ScoreFactor[];
+  /** The lexicographic sort key (T12691). */
+  key?: ScoreTaskKey;
 }