@cleocode/contracts 2026.9.23 → 2026.9.25

package/src/operations/nexus.ts

@@ -124,6 +124,10 @@ export interface NexusProjectRecord {
   lastIndexed: string | null;
   /** Code intelligence stats from the last index run. */
   stats: NexusProjectStats;
+  /** ISO 8601 instant of the last health check, sync or git probe (T12512). */
+  lastProbedAt?: string | null;
+  /** ISO 8601 instant of the last real CLI use inside the project (T12512). */
+  lastOpenedAt?: string | null;
 }
 
 /** A single cross-project task reference tuple. */
@@ -1383,6 +1387,12 @@ export interface NexusProjectGitState {
   branch: string | null;
   /** HEAD commit; `null` for an unborn branch or when the probe failed. */
   headSha: string | null;
+  /**
+   * ISO 8601 UTC instant HEAD was committed (`git log -1 --format=%cI`,
+   * normalized to `Z`); `null` for an unborn branch or when the probe failed
+   * before reading it (T12721).
+   */
+  headCommittedAt: string | null;
   /** `true` when HEAD is detached. */
   detached: boolean;
   /** `true` for a shallow clone (ahead/behind may be truncated by the graft). */
@@ -1464,6 +1474,276 @@ export interface NexusProjectsStatusResult {
   };
 }
 
+/**
+ * A condition on one project location in the fleet view (T12513).
+ *
+ * - `missing` — the location is recorded `missing`, or its last probe found no directory.
+ * - `dirty` — the last probe saw tracked changes or untracked files.
+ * - `behind` / `ahead` — the upstream had commits HEAD lacks / HEAD has commits
+ *   the upstream lacks, as of the LAST FETCH (see `remote.fetchedAt`).
+ * - `stale` — never probed, probed longer ago than the staleness window, or its
+ *   remote was last fetched longer ago than the window (or never).
+ * - `errored` — the last probe recorded a probe error.
+ * - `unprobed` — no probe row exists for the location yet.
+ */
+export type NexusFleetFlag =
+  | 'missing'
+  | 'dirty'
+  | 'behind'
+  | 'ahead'
+  | 'stale'
+  | 'errored'
+  | 'unprobed';
+
+/** Parameters for `nexus.projects.fleet` (T12513). Filters combine with AND. */
+export interface NexusProjectsFleetParams {
+  /** Keep only locations on this device: a device id, a hostname, or `current`. */
+  device?: string;
+  /** Keep projects with a `missing` location. */
+  missing?: boolean;
+  /** Keep projects with a `dirty` location. */
+  dirty?: boolean;
+  /** Keep projects with a location `behind` its upstream (as of the last fetch). */
+  behind?: boolean;
+  /** Keep projects with a location `ahead` of its upstream (as of the last fetch). */
+  ahead?: boolean;
+  /** Keep projects with a `stale` location. */
+  stale?: boolean;
+  /** Keep projects with a location whose last probe errored. */
+  errored?: boolean;
+  /** Staleness window for probes, fetches and heartbeats, ms. Default 24h. */
+  staleAfterMs?: number;
+  /** Page size (projects). Default 50, max 500; `0` returns every match. */
+  limit?: number;
+  /** Projects skipped before the page. Default 0. */
+  offset?: number;
+}
+
+/** One device as the fleet view shows it (T12513). */
+export interface NexusFleetDevice {
+  /** Stable device id (`<cleoHome>/device-id`). */
+  deviceId: string;
+  /**
+   * Hostname at the last heartbeat; `null` when the device never sent one.
+   * **Device-local, never mirrored** to the cloud.
+   */
+  hostname: string | null;
+  /** Operating system at the last heartbeat. */
+  os: string | null;
+  /** CPU architecture at the last heartbeat. */
+  arch: string | null;
+  /** CLEO version at the last heartbeat. */
+  cleoVersion: string | null;
+  /** ISO 8601 instant of the last heartbeat; `null` if never. */
+  lastHeartbeatAt: string | null;
+  /** `true` when the last heartbeat is unknown or older than the staleness window. */
+  heartbeatStale: boolean;
+  /** `true` for the device running this command. */
+  current: boolean;
+}
+
+/** Per-device counts in the fleet view (T12513). */
+export interface NexusFleetDeviceSummary extends NexusFleetDevice {
+  /** Visible (live or missing) locations on the device. */
+  locations: number;
+  /** Of those, locations flagged `missing`. */
+  missing: number;
+  /** Of those, locations flagged `dirty`. */
+  dirty: number;
+  /** Of those, locations flagged `behind`. */
+  behind: number;
+  /** Of those, locations flagged `stale`. */
+  stale: number;
+}
+
+/**
+ * Version of the fleet/presence shape a {@link NexusProjectsFleetResult} and
+ * the cloud `ReplicaPresence` built from it conform to (T12721). A positive
+ * integer, sent as `ReplicaPresence.schemaVersion`; bump it when a field the
+ * presence mapper reads changes meaning.
+ *
+ * - `1` — T12721: `headCommittedAt`, `replicaId`, device-local field markers.
+ */
+export const NEXUS_FLEET_SCHEMA_VERSION = 1;
+
+/**
+ * Last recorded git state of one location (T12513, from T12511's probe rows).
+ *
+ * The cloud mirrors only a path-free projection of it (`ReplicaPresence`,
+ * built by core's `toReplicaPresence`): dirty, ahead, behind, a remote-sync
+ * enum and `headCommittedAt`. Every field marked **device-local, never
+ * mirrored** stays on the device; `branch` leaves it only on explicit opt-in.
+ */
+export interface NexusFleetGitSummary {
+  /**
+   * Checked-out branch; `null` when detached or unknown. **Mirrored only on
+   * explicit opt-in** (branch names can be sensitive).
+   */
+  branch: string | null;
+  /** HEAD commit. **Device-local, never mirrored.** */
+  headSha: string | null;
+  /**
+   * ISO 8601 UTC instant HEAD was committed; `null` when unknown (unborn
+   * branch, failed probe, or a row probed before T12721). Mirrored as
+   * `ReplicaPresence.git.lastCommitAt`.
+   */
+  headCommittedAt: string | null;
+  /** `true` when HEAD is detached. */
+  detached: boolean;
+  /** Tracked entries with changes. */
+  dirtyCount: number | null;
+  /** Untracked, not-ignored entries. */
+  untrackedCount: number | null;
+  /** Remote side, as of the last fetch — never "now". */
+  remote: {
+    /** Remote name. **Device-local, never mirrored.** */
+    name: string | null;
+    /** Remote URL, credentials removed. **Device-local, never mirrored.** */
+    url: string | null;
+    /** Upstream ref (e.g. `origin/main`). **Device-local, never mirrored.** */
+    upstream: string | null;
+    /** Upstream tracking-ref commit. **Device-local, never mirrored.** */
+    headSha: string | null;
+    /** Commits on HEAD not on the upstream. */
+    ahead: number | null;
+    /** Commits on the upstream not on HEAD. */
+    behind: number | null;
+    /** ISO 8601 instant of the last fetch; `null` if never. */
+    fetchedAt: string | null;
+    /** `true` when the last fetch is unknown or older than the staleness window. */
+    stale: boolean;
+  };
+  /** ISO 8601 instant of the probe that recorded this state. */
+  probedAt: string;
+  /** `true` when `probedAt` is older than the staleness window. */
+  probeStale: boolean;
+  /** Probe error code, `null` on success. */
+  probeErrorCode: NexusGitProbeErrorCode | null;
+  /**
+   * Probe error detail (git's stderr, an errno, a path). **Device-local, never
+   * mirrored**: presence carries only `remote: 'unknown'` for an errored probe.
+   */
+  probeError: string | null;
+}
+
+/** One place a project lives, on one device (T12513). */
+export interface NexusFleetLocation {
+  /** Device the location is on. */
+  deviceId: string;
+  /**
+   * Replica identity of this location in the cloud (the `:replicaId` of
+   * `PUT /v1/projects/:projectId/replicas/:replicaId/presence`), or `null`.
+   *
+   * Always `null` today: the store has no stable per-replica id yet. T12675's
+   * store-instance id becomes this `replicaId` (it must satisfy the cloud
+   * `ReplicaId` shape, a UUIDv7). It is never derived from the path, the
+   * device id or a hash of either — a derived id changes on a move and is not
+   * stable. A caller must not send presence for a location whose `replicaId`
+   * is `null`.
+   */
+  replicaId: string | null;
+  /**
+   * Hostname of that device, when it has sent a heartbeat. **Device-local,
+   * never mirrored.**
+   */
+  hostname: string | null;
+  /** `true` when the location is on the device running this command. */
+  current: boolean;
+  /** Checkout root on that device. **Device-local, never mirrored.** */
+  path: string;
+  /** Location lifecycle state. */
+  state: 'live' | 'missing';
+  /** ISO 8601 instant the location was last encountered. */
+  lastSeen: string;
+  /** Last recorded git state; `null` when never probed. */
+  git: NexusFleetGitSummary | null;
+  /** Conditions that hold for this location. */
+  flags: NexusFleetFlag[];
+}
+
+/** One project in the fleet view (T12513). */
+export interface NexusFleetProject {
+  /** Immutable project id. */
+  projectId: string;
+  /** Registered name (not unique). */
+  name: string;
+  /** ISO 8601 instant of the last real CLI use; `null` if never recorded. */
+  lastOpenedAt: string | null;
+  /** ISO 8601 instant of the last health check, sync or git probe; `null` if never. */
+  lastProbedAt: string | null;
+  /** Number of distinct devices holding a visible location. */
+  deviceCount: number;
+  /** Union of the flags of its locations. */
+  flags: NexusFleetFlag[];
+  /** Every visible location (within the `device` filter), by device then path. */
+  locations: NexusFleetLocation[];
+}
+
+/**
+ * Result of `nexus.projects.fleet` (T12513). Counts come first; `projects` is
+ * one page. Read-only: it reports the probe rows recorded by
+ * `nexus.projects.status` and never runs git.
+ */
+export interface NexusProjectsFleetResult {
+  /** Projects in the registry. */
+  total: number;
+  /** Projects matching the filters. */
+  matched: number;
+  /** Projects on this page. */
+  returned: number;
+  /** Offset of this page. */
+  offset: number;
+  /** Page size applied (`0` = unbounded). */
+  limit: number;
+  /** `true` when more matches follow this page. */
+  hasMore: boolean;
+  /** Staleness window applied, ms. */
+  staleAfterMs: number;
+  /** ISO 8601 instant staleness was evaluated at. */
+  generatedAt: string;
+  /** Device the command ran on. */
+  currentDeviceId: string;
+  /**
+   * Fleet/presence shape version this result conforms to
+   * ({@link NEXUS_FLEET_SCHEMA_VERSION}); sent as `ReplicaPresence.schemaVersion`.
+   */
+  schemaVersion: number;
+  /**
+   * Fleet-wide counts of PROJECTS with at least one location in each
+   * condition. Scoped by `device` ONLY — the flag filters (`missing`, `dirty`,
+   * `behind`, `ahead`, `stale`, `errored`) never narrow it, so it always shows
+   * the whole fleet (or the whole device) while `matched` counts the filter.
+   */
+  summary: {
+    /** Projects with a visible location. */
+    located: number;
+    /** Distinct visible locations. */
+    locations: number;
+    /** Projects flagged per condition. */
+    missing: number;
+    /** Projects with a dirty location. */
+    dirty: number;
+    /** Projects with a location behind its upstream. */
+    behind: number;
+    /** Projects with a location ahead of its upstream. */
+    ahead: number;
+    /** Projects with a stale location. */
+    stale: number;
+    /** Projects with an errored probe. */
+    errored: number;
+    /** Projects with a never-probed location. */
+    unprobed: number;
+  };
+  /**
+   * Every device holding a visible location or known by heartbeat, with
+   * per-device location counts. Like `summary`, scoped by `device` only —
+   * never by the flag filters.
+   */
+  devices: NexusFleetDeviceSummary[];
+  /** This page of projects, by name then id. */
+  projects: NexusFleetProject[];
+}
+
 /** Parameters for `nexus.projects.register`. */
 export interface NexusProjectsRegisterParams {
   /** Path to the project directory (required). */
@@ -2115,6 +2395,7 @@ export type NexusOps = {
   readonly 'projects.scan': readonly [NexusProjectsScanParams, NexusProjectsScanResult];
   readonly 'projects.clean': readonly [NexusProjectsCleanParams, NexusProjectsCleanResult];
   readonly 'projects.status': readonly [NexusProjectsStatusParams, NexusProjectsStatusResult];
+  readonly 'projects.fleet': readonly [NexusProjectsFleetParams, NexusProjectsFleetResult];
   readonly 'refresh-bridge': readonly [NexusRefreshBridgeParams, NexusRefreshBridgeResult];
   readonly diff: readonly [NexusDiffParams, NexusDiffResult];
   readonly 'query-cte': readonly [NexusQueryCteParams, NexusQueryCteResult];

package/src/operations/orchestrate.ts

@@ -432,8 +432,12 @@ export interface OrchestrateBootstrapParams {
   speed?: 'fast' | 'full' | 'complete';
 }
 export interface BrainState {
-  /** Currently active session summary. @task T963 */
-  session?: { id: string; name: string; status: string; startedAt: string };
+  /**
+   * Session summary: the caller's bound session, else the newest active row.
+   * `unbound: true` marks the latter, which may be another agent's (T12500).
+   * @task T963
+   */
+  session?: { id: string; name: string; status: string; startedAt: string; unbound?: boolean };
   /** Current task context. @task T963 */
   currentTask?: { id: string; title: string; status: string };
   /** Suggested next task with score. @task T963 */

package/src/operations/output-contracts-data.ts

@@ -63,6 +63,26 @@ import {
  * exact shape whose absence produced `cleo show --field /data/title` →
  * `E_FIELD_NOT_FOUND`.
  */
+/**
+ * JSON schema of a {@link TaskClaim} lease (T12502), shared by `tasks.show`,
+ * `tasks.start` and `tasks.claim`.
+ */
+const TASK_CLAIM_SCHEMA = {
+  type: 'object',
+  description:
+    'Agent claim lease (T12502): the holder session, its agent, and when the lease lapses unless renewed. Absent when unclaimed.',
+  required: ['sessionId', 'agentId', 'claimedAt', 'leaseExpiresAt'],
+  properties: {
+    sessionId: { type: 'string', description: 'Session holding the lease.' },
+    agentId: { type: ['string', 'null'], description: 'Agent identity of the holder.' },
+    claimedAt: { type: 'string', description: 'When the lease was taken (ISO-8601 UTC).' },
+    leaseExpiresAt: {
+      type: 'string',
+      description: 'When the lease lapses unless renewed (ISO-8601 UTC).',
+    },
+  },
+} as const;
+
 const tasksShowOutputContract: OperationOutputContract = {
   operation: 'tasks.show',
   shapeNote:
@@ -70,6 +90,8 @@ const tasksShowOutputContract: OperationOutputContract = {
     'Mutation envelopes are FLAT by contrast (/data/created/0, /data/updated/0), which is ' +
     'the asymmetry that produced GH #1225/#1239/#1231. ' +
     '`view` may be null. `acRows` and `relations` are conditional. ' +
+    'The default (MVI) projection withholds each `acRows` UUID and names it once in ' +
+    '`/data/_withheld` as `acRows/*/id` (T12523); cite a criterion by `alias` (AC1..n). ' +
     '`description`, `acceptance` and `verification` are withheld by the default (MVI) ' +
     'projection but `--field` resolves them transparently (T12108) — no `--full` needed. ' +
     'Evidence is NOT a task field: it lives at /data/task/verification/evidence ' +
@@ -92,6 +114,18 @@ const tasksShowOutputContract: OperationOutputContract = {
           priority: { type: 'string' },
           type: { type: 'string' },
           parentId: { type: ['string', 'null'] },
+          // T12503: the optimistic-concurrency version agents pass to --if-match.
+          updatedAt: {
+            type: ['string', 'null'],
+            description:
+              'Task version for optimistic concurrency: pass it to `cleo update|complete --if-match`.',
+          },
+          // T12502: the human assignee and the agent claim lease are separate.
+          assignee: {
+            type: ['string', 'null'],
+            description: 'Human / owner assignee. Separate from `claim`.',
+          },
+          claim: TASK_CLAIM_SCHEMA,
         },
       },
       view: {
@@ -105,7 +139,13 @@ const tasksShowOutputContract: OperationOutputContract = {
       },
       acRows: {
         type: 'array',
-        description: 'Acceptance-criterion rows (id, alias AC<n>, ordinal, text). Optional.',
+        description:
+          'Acceptance-criterion rows (alias AC<n>, ordinal, text; the UUID id only with --full). Optional.',
+      },
+      _withheld: {
+        type: 'object',
+        description:
+          'Fields the default projection withheld from list elements, e.g. `acRows/*/id` → UTF-8 byte total. Absent with --full.',
       },
       relations: {
         type: 'object',
@@ -120,6 +160,14 @@ const tasksShowOutputContract: OperationOutputContract = {
     '/data/task/priority',
     '/data/task/type',
     '/data/task/parentId',
+    // T12503 — the optimistic-concurrency version for `--if-match`; withheld
+    // by the MVI projection, resolved from the full record by `--field`.
+    '/data/task/updatedAt',
+    // T12502 — the agent claim lease (withheld by MVI; resolved by --field).
+    '/data/task/assignee',
+    '/data/task/claim',
+    '/data/task/claim/sessionId',
+    '/data/task/claim/leaseExpiresAt',
     // T12127 (GH #1231) — withheld by the MVI projection but resolvable
     // through `--field` since T12108. They were absent from this list, so the
     // remediation an agent is shown on a failed pointer never mentioned the
@@ -494,6 +542,78 @@ const tasksAssigneeOutputContract: OperationOutputContract = {
   fieldPointers: ['/data/taskId', '/data/assignee', '/data/assigned'],
 };
 
+/**
+ * OUTPUT contract for `tasks.start` (T12502).
+ *
+ * Grounded in `TasksStartQueryResult`: `{ taskId, previousTask, claim }`.
+ */
+const tasksStartOutputContract: OperationOutputContract = {
+  operation: 'tasks.start',
+  shapeNote:
+    'The claim lease this start holds is at /data/claim (null when the caller is not bound to a session). ' +
+    'Another session holding the task fails with E_TASK_CLAIMED (exit 35); error.details.holder names it.',
+  dataSchema: {
+    type: 'object',
+    required: ['taskId', 'previousTask'],
+    additionalProperties: true,
+    properties: {
+      taskId: { type: 'string', description: 'The task now active.' },
+      previousTask: { type: ['string', 'null'], description: 'The task active before, if any.' },
+      claim: { ...TASK_CLAIM_SCHEMA, type: ['object', 'null'] },
+    },
+  },
+  fieldPointers: [
+    '/data/taskId',
+    '/data/previousTask',
+    '/data/claim',
+    '/data/claim/sessionId',
+    '/data/claim/leaseExpiresAt',
+  ],
+};
+
+/**
+ * OUTPUT contract for `tasks.claim` (T12502).
+ *
+ * Grounded in `TasksClaimResult`: `{ taskId, agentId, claim }`.
+ */
+const tasksClaimOutputContract: OperationOutputContract = {
+  operation: 'tasks.claim',
+  shapeNote:
+    'The lease now held by your session is at /data/claim; renew it with --renew. ' +
+    'Another holder fails with E_TASK_CLAIMED (exit 35): --take-over (expired) or --force-claim (live).',
+  dataSchema: {
+    type: 'object',
+    required: ['taskId', 'agentId', 'claim'],
+    additionalProperties: true,
+    properties: {
+      taskId: { type: 'string', description: 'The claimed task.' },
+      agentId: { type: ['string', 'null'], description: 'Agent recorded with the lease.' },
+      claim: TASK_CLAIM_SCHEMA,
+    },
+  },
+  fieldPointers: ['/data/taskId', '/data/agentId', '/data/claim', '/data/claim/leaseExpiresAt'],
+};
+
+/**
+ * OUTPUT contract for `tasks.unclaim` (T12502).
+ *
+ * Grounded in `TasksUnclaimResult`: `{ taskId, released }`.
+ */
+const tasksUnclaimOutputContract: OperationOutputContract = {
+  operation: 'tasks.unclaim',
+  shapeNote: '/data/released is true when a lease was cleared, false when the task was unclaimed.',
+  dataSchema: {
+    type: 'object',
+    required: ['taskId', 'released'],
+    additionalProperties: true,
+    properties: {
+      taskId: { type: 'string', description: 'The released task.' },
+      released: { type: 'boolean', description: 'Whether a lease was cleared.' },
+    },
+  },
+  fieldPointers: ['/data/taskId', '/data/released'],
+};
+
 // ---------------------------------------------------------------------------
 // admin.config.* — config-as-domain (T11917 · M5/AC3 · ConfigManifest cascade)
 // ---------------------------------------------------------------------------
@@ -649,6 +769,10 @@ export const OUTPUT_CONTRACTS: OperationOutputContractRegistry = {
   'tasks.reorder-rank': tasksReorderRankOutputContract,
   'tasks.bulk-move': tasksBulkMoveOutputContract,
   'tasks.assignee': tasksAssigneeOutputContract,
+  // T12502 — leased task claims.
+  'tasks.start': tasksStartOutputContract,
+  'tasks.claim': tasksClaimOutputContract,
+  'tasks.unclaim': tasksUnclaimOutputContract,
   'admin.config.get': adminConfigGetOutputContract,
   'admin.config.list': adminConfigListOutputContract,
   'admin.config.validate': adminConfigValidateOutputContract,

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). */
@@ -1680,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.
@@ -1824,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)

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. */