@cleocode/contracts 2026.9.23 → 2026.9.24

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

@@ -723,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).
    *
@@ -1020,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/score-task-priority.ts

@@ -26,7 +26,7 @@ export interface ScoreTaskInput {
   labels?: string[];
   /** Severity axis (orthogonal to priority); unset for most tasks. */
   severity?: TaskSeverity | null;
-  /** Kind axis; a `bug` with no severity is scored at the default bug severity (T12661). */
+  /** Kind axis; not part of the order — an unset severity is unknown, never imputed from `kind` (D11161). */
   kind?: TaskKind | null;
 }