@cleocode/contracts 2026.9.23 → 2026.9.24

package/src/dispatch/operations-registry.ts

@@ -3072,6 +3072,14 @@ export const OPERATIONS: OperationDef[] = [
         description: 'taskId parameter',
         cli: { positional: true },
       },
+      {
+        name: 'expectedUpdatedAt',
+        type: 'string',
+        required: false,
+        description:
+          'Optimistic-concurrency guard: fail with E_CONFLICT unless the task updatedAt still equals this value',
+        cli: { flag: 'if-match' },
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -3748,7 +3756,8 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'mutate',
     domain: 'tasks',
     operation: 'start',
-    description: 'tasks.start (mutate)',
+    description:
+      "tasks.start (mutate) — start work and take the caller session's leased claim (E_TASK_CLAIMED when another session holds it)",
     tier: 0,
     idempotent: false,
     sessionRequired: false,
@@ -3761,6 +3770,20 @@ export const OPERATIONS: OperationDef[] = [
         description: 'taskId parameter',
         cli: { positional: true },
       },
+      {
+        name: 'takeOver',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's EXPIRED claim lease (audited)",
+        cli: { flag: 'take-over' },
+      },
+      {
+        name: 'forceClaim',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's LIVE claim lease (audited)",
+        cli: { flag: 'force-claim' },
+      },
     ] satisfies ParamDef[],
   },
   {
@@ -3869,11 +3892,12 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'mutate',
     domain: 'tasks',
     operation: 'claim',
-    description: 'tasks.claim (mutate) — claim a task by assigning it to the current session',
+    description:
+      "tasks.claim (mutate) — take, renew or override the caller session's leased claim on a task (never the human assignee)",
     tier: 0,
     idempotent: false,
     sessionRequired: true,
-    requiredParams: ['taskId', 'agentId'],
+    requiredParams: ['taskId'],
     params: [
       {
         name: 'taskId',
@@ -3884,8 +3908,27 @@ export const OPERATIONS: OperationDef[] = [
       {
         name: 'agentId',
         type: 'string',
-        required: true,
-        description: 'Agent ID to assign the task to',
+        required: false,
+        description:
+          "Agent ID recorded with the lease (default: the session's agent / CLEO_AGENT_ID)",
+      },
+      {
+        name: 'renew',
+        type: 'boolean',
+        required: false,
+        description: "Renew the caller's own lease",
+      },
+      {
+        name: 'takeOver',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's EXPIRED lease (audited)",
+      },
+      {
+        name: 'forceClaim',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's LIVE lease (audited)",
       },
     ],
   },
@@ -3893,7 +3936,8 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'mutate',
     domain: 'tasks',
     operation: 'unclaim',
-    description: 'tasks.unclaim (mutate) — unclaim a task by removing the current assignee',
+    description:
+      "tasks.unclaim (mutate) — release the caller session's claim lease (never the human assignee)",
     tier: 0,
     idempotent: false,
     sessionRequired: true,
@@ -3905,6 +3949,12 @@ export const OPERATIONS: OperationDef[] = [
         required: true,
         description: 'Task ID to unclaim',
       },
+      {
+        name: 'forceClaim',
+        type: 'boolean',
+        required: false,
+        description: "Release another session's lease (audited)",
+      },
     ],
   },
   {
@@ -4164,6 +4214,20 @@ export const OPERATIONS: OperationDef[] = [
         description:
           'When true (default), adds toTaskId as a dependency on fromTaskId so it cannot complete before the pivot resolves',
       },
+      {
+        name: 'takeOver',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's EXPIRED claim on toTaskId (audited)",
+        cli: { flag: 'take-over' },
+      },
+      {
+        name: 'forceClaim',
+        type: 'boolean',
+        required: false,
+        description: "Take over another session's LIVE claim on toTaskId (audited)",
+        cli: { flag: 'force-claim' },
+      },
     ],
   },
   // parallel.start and parallel.end merged into orchestrate.parallel via action param (T5615)
@@ -6907,6 +6971,80 @@ export const OPERATIONS: OperationDef[] = [
     params: [],
   },
 
+  {
+    gateway: 'query' as const,
+    domain: 'nexus',
+    operation: 'projects.fleet',
+    description:
+      'nexus.projects.fleet (query) — fleet view: every project with its location on each device, last recorded git state (local, and remote as of the last fetch) and staleness; paged, counts first, read-only',
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'device',
+        type: 'string',
+        required: false,
+        description: 'Only locations on this device (device id, hostname, or current)',
+      },
+      {
+        name: 'missing',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects with a missing location',
+      },
+      {
+        name: 'dirty',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects with a dirty location',
+      },
+      {
+        name: 'behind',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects with a location behind its upstream (as of the last fetch)',
+      },
+      {
+        name: 'ahead',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects with a location ahead of its upstream (as of the last fetch)',
+      },
+      {
+        name: 'stale',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects with a never-probed, old-probe or old-fetch location',
+      },
+      {
+        name: 'errored',
+        type: 'boolean',
+        required: false,
+        description: 'Only projects whose last probe recorded an error',
+      },
+      {
+        name: 'staleAfterMs',
+        type: 'number',
+        required: false,
+        description: 'Staleness window for probes, fetches and heartbeats (default 24h)',
+      },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Page size in projects (default 50, max 500; 0 = all)',
+      },
+      {
+        name: 'offset',
+        type: 'number',
+        required: false,
+        description: 'Projects skipped before the page',
+      },
+    ],
+  },
+
   {
     gateway: 'mutate' as const,
     domain: 'nexus',

package/src/doctor.ts

@@ -880,6 +880,15 @@ export interface DbSubstrateSurveyOptions {
    * `false` → leave the corrupt DB in place; only report it.
    */
   autoQuarantine?: boolean;
+  /**
+   * Directory the survey was invoked from (T12708). Quarantine moves a
+   * project's live store; from a linked worktree of that project it needs
+   * {@link DbSubstrateSurveyOptions.confirmOwnerStore}, and it never moves a
+   * store inside a worktree. Defaults to the process directory.
+   */
+  cwd?: string;
+  /** Confirm quarantining the owning project's LIVE store from a worktree (T12708). */
+  confirmOwnerStore?: boolean;
 }
 
 /**

package/src/exit-codes.ts

@@ -75,6 +75,13 @@ export enum ExitCode {
   SCOPE_CONFLICT = 32,
   SCOPE_INVALID = 33,
   TASK_NOT_IN_SCOPE = 34,
+  /**
+   * Another session holds the claim lease on the task (`cleo start`,
+   * `cleo claim`, spawn). LAFS code `E_TASK_CLAIMED`; the details
+   * (`TaskClaimedDetails`) name the holder session and agent, the lease
+   * expiry, and the explicit, audited override: `--take-over` for an expired
+   * lease, `--force-claim` for a live one. @task T12502
+   */
   TASK_CLAIMED = 35,
   SESSION_REQUIRED = 36,
   SESSION_CLOSE_BLOCKED = 37,

package/src/index.ts

@@ -362,6 +362,12 @@ export type {
   QueryTasksResult,
   TaskAuditLogQuery,
   TaskAuditLogRow,
+  TaskClaimedDetails,
+  TaskClaimGuard,
+  TaskClaimMode,
+  TaskClaimRequest,
+  TaskConflictChange,
+  TaskConflictDetails,
   TaskFieldUpdates,
   TaskPopulation,
   TaskQueryFilters,
@@ -808,6 +814,7 @@ export type {
   KnowledgeEvidenceRef,
   KnowledgeFileEvidence,
   KnowledgeHealth,
+  KnowledgeHealthSummary,
   KnowledgeRepairAction,
   KnowledgeRepairClass,
   KnowledgeRepairFinding,
@@ -1492,6 +1499,12 @@ export type {
   NexusDiscoverHit,
   NexusDiscoverParams,
   NexusDiscoverResult,
+  NexusFleetDevice,
+  NexusFleetDeviceSummary,
+  NexusFleetFlag,
+  NexusFleetGitSummary,
+  NexusFleetLocation,
+  NexusFleetProject,
   NexusFlowEntry,
   NexusFlowsParams,
   NexusFlowsResult,
@@ -1541,6 +1554,8 @@ export type {
   NexusProjectsCleanRemoval,
   NexusProjectsCleanResult,
   NexusProjectsCleanUnreadable,
+  NexusProjectsFleetParams,
+  NexusProjectsFleetResult,
   NexusProjectsListParams,
   NexusProjectsListResult,
   NexusProjectsRegisterParams,
@@ -1621,6 +1636,7 @@ export type {
   NexusWhyResult,
   NexusWikiParams,
 } from './operations/nexus.js';
+export { NEXUS_FLEET_SCHEMA_VERSION } from './operations/nexus.js';
 // === Nexus Scope Contracts (T9145 + T9146) ===
 export type {
   MetaWithNexusScope,
@@ -2500,6 +2516,7 @@ export type {
   SeverityAttestation,
   SignedSeverityAttestation,
   Task,
+  TaskClaim,
   TaskCreate,
   // T944 new axes (T9072: renamed TaskRole → TaskKind)
   TaskKind,
@@ -2890,6 +2907,12 @@ export {
 export type {
   ChoiceDecisionAnswer,
   ChoiceDecisionQuestion,
+  DecideProfileConnection,
+  DecideProfileListResult,
+  DecideProfileProbe,
+  DecideProfileSummary,
+  DecideProfileUrlSource,
+  DecideProviderState,
   DecisionAnswer,
   DecisionBatchItem,
   DecisionInstructions,
@@ -2912,6 +2935,9 @@ export type {
 export {
   choiceDecisionAnswerSchema,
   choiceDecisionQuestionSchema,
+  DECIDE_DEFAULT_PROFILE_NAME,
+  DECIDE_PROFILE_DEFAULT_URL,
+  DECIDE_PROFILE_NAME_PATTERN,
   DECISION_OUTCOME_SOURCES,
   DECISION_PROVIDER_KINDS,
   DECISION_QUESTION_TYPES,
@@ -2926,6 +2952,7 @@ export {
   decisionQuestionTypeSchema,
   decisionRequestSchema,
   decisionStateSchema,
+  JEV_DEFAULT_BASE_URL,
   JEV_MINIMUM_CAPABILITIES,
   LAYAHOST_BASE_URL,
   LAYAHOST_DEFAULT_MODEL,
@@ -2949,4 +2976,25 @@ export type {
 } from './decide-sites.js';
 export { DECISION_RUNGS, DECISION_SITE_MODES } from './decide-sites.js';
 
+export type {
+  NexusAccountErrorCode,
+  NexusAccountMe,
+  NexusAccountOrganization,
+  NexusAccountStatus,
+  NexusAccountUser,
+  NexusLoginResult,
+  NexusLogoutResult,
+  NexusProjectLink,
+  NexusProjectLinkResult,
+  NexusSessionState,
+} from './nexus-account.js';
+export {
+  NEXUS_ACCOUNT_ERROR_CODES,
+  NEXUS_CLI_CLIENT_ID,
+  NEXUS_DEFAULT_API_URL,
+  NEXUS_LOGIN_TARGET,
+  nexusAccountMeSchema,
+  nexusAccountOrganizationSchema,
+  nexusAccountUserSchema,
+} from './nexus-account.js';
 export { isStorableTaskId, isTaskId, TASK_ID_REGEX, type TaskId } from './task-id.js';

package/src/knowledge-health.ts

@@ -258,6 +258,28 @@ export interface KnowledgeHealth {
   findings: KnowledgeRepairFinding[];
 }
 
+/**
+ * Orientation summary of {@link KnowledgeHealth} for envelopes that already
+ * carry the coverage object at their top level (`briefing.show`'s
+ * `knowledgeCoverage`, `focus.show`'s `coverage`).
+ *
+ * The coverage object is emitted once per envelope; this summary points at it
+ * through {@link KnowledgeHealthSummary.coverageRef} instead of repeating it
+ * (T12522). Every other field keeps the {@link KnowledgeHealth} meaning. The
+ * full assessment, coverage included, remains available from
+ * `cleo doctor knowledge`.
+ *
+ * @task T12522
+ */
+export interface KnowledgeHealthSummary extends Omit<KnowledgeHealth, 'coverage'> {
+  /**
+   * JSON Pointer, relative to the envelope's `data`, of the coverage object
+   * this summary describes — e.g. `/knowledgeCoverage` (briefing) or
+   * `/coverage` (focus). Prefix `/data` for `cleo ... --field`.
+   */
+  coverageRef: string;
+}
+
 /** Responsibility for resolving a knowledge defect. */
 export type KnowledgeRepairClass = 'automatic' | 'agent-resolvable' | 'owner-decision';
 

package/src/nexus-account.ts

@@ -0,0 +1,181 @@
+/**
+ * Cleo Nexus account contracts: the CLI's signed-in session with the Cleo
+ * Nexus API (device-code login, logout, status, project link).
+ *
+ * The API is a better-auth app: the device-code grant (RFC 8628) issues a
+ * session token that the bearer plugin accepts on every `/v1` route. These
+ * types describe what CLEO emits and persists about that session. None of
+ * them carries the token: results and status rows are secret-free by
+ * construction, so they are safe in LAFS envelopes and logs.
+ *
+ * Not part of `./cloud`: that directory mirrors the server's
+ * `@cleo-nexus/shared` contract one-to-one. The `/v1/account/me` subset
+ * below is read-only and client-side.
+ *
+ * This file is types + zod schemas + const data only (arch gate 10).
+ *
+ * @task T12712
+ * @epic T12322
+ */
+
+import { z } from 'zod';
+
+/** Production Cleo Nexus API origin. */
+export const NEXUS_DEFAULT_API_URL = 'https://api.cleocode.dev';
+
+/** The OAuth client id the Nexus API accepts for the device-code grant. */
+export const NEXUS_CLI_CLIENT_ID = 'cleo-cli';
+
+/**
+ * The reserved `cleo login` target for a Cleo Nexus account. It is checked
+ * before the LLM provider registry, so no provider can shadow it.
+ */
+export const NEXUS_LOGIN_TARGET = 'nexus';
+
+/** Stable error codes of the Nexus account flows. */
+export const NEXUS_ACCOUNT_ERROR_CODES = [
+  'E_NEXUS_INVALID_API_URL',
+  'E_NEXUS_NOT_SIGNED_IN',
+  'E_NEXUS_SESSION_EXPIRED',
+  'E_NEXUS_DEVICE_CODE_START_FAILED',
+  'E_NEXUS_UNTRUSTED_VERIFICATION_URI',
+  'E_NEXUS_DEVICE_CODE_EXPIRED',
+  'E_NEXUS_ACCESS_DENIED',
+  'E_NEXUS_DEVICE_CODE_FAILED',
+  'E_NEXUS_REVOKE_FAILED',
+  'E_NEXUS_REQUEST_FAILED',
+  'E_NEXUS_NOT_A_PROJECT',
+  'E_NEXUS_INVALID_LABEL',
+] as const;
+
+/** One of {@link NEXUS_ACCOUNT_ERROR_CODES}. */
+export type NexusAccountErrorCode = (typeof NEXUS_ACCOUNT_ERROR_CODES)[number];
+
+/** The signed-in user, as `/v1/account/me` reports it. */
+export const nexusAccountUserSchema = z.object({
+  id: z.string(),
+  email: z.string(),
+  name: z.string().nullable().optional(),
+});
+
+/** A user's organization membership, as `/v1/account/me` reports it. */
+export const nexusAccountOrganizationSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  slug: z.string().nullable().optional(),
+  role: z.string().optional(),
+  /** `true` for the personal organization created at sign-up. */
+  personal: z.boolean().optional(),
+});
+
+/**
+ * The subset of `GET /v1/account/me` the CLI reads. Unknown fields are
+ * ignored (zod strips them), so the server can grow the payload freely.
+ */
+export const nexusAccountMeSchema = z.object({
+  user: nexusAccountUserSchema,
+  organizations: z.array(nexusAccountOrganizationSchema).default([]),
+});
+
+/** Parsed `GET /v1/account/me` subset. */
+export type NexusAccountMe = z.infer<typeof nexusAccountMeSchema>;
+
+/** A signed-in user (no secrets). */
+export type NexusAccountUser = z.infer<typeof nexusAccountUserSchema>;
+
+/** An organization reference (no secrets). */
+export type NexusAccountOrganization = z.infer<typeof nexusAccountOrganizationSchema>;
+
+/**
+ * Session state for one API origin.
+ *
+ * - `signed-in`      — a token is stored and, when checked live, the API accepted it.
+ * - `unverified`     — a token is stored but the API could not be reached.
+ * - `expired`        — the API answered 401: the session expired or was revoked.
+ * - `not-signed-in`  — no token is stored for the origin.
+ */
+export type NexusSessionState = 'signed-in' | 'unverified' | 'expired' | 'not-signed-in';
+
+/** Secret-free status row for `cleo status` and `cleo auth list`. */
+export interface NexusAccountStatus {
+  /** API origin the row describes, e.g. `https://api.cleocode.dev`. */
+  apiUrl: string;
+  /** Session state. */
+  state: NexusSessionState;
+  /** Signed-in user's email, when known. */
+  email: string | null;
+  /** Primary organization (the personal one, else the first), when known. */
+  organization: string | null;
+  /** ISO time the stored token expires, when the server said so. */
+  expiresAt: string | null;
+  /** One human line: "signed in as a@b.c (Org)", "session expired", "not signed in". */
+  summary: string;
+}
+
+/** Result of `cleo login nexus` (never carries the token). */
+export interface NexusLoginResult {
+  /** API origin the session belongs to. */
+  apiUrl: string;
+  /** The signed-in user, when `/v1/account/me` answered. */
+  user: NexusAccountUser | null;
+  /** Primary organization, when known. */
+  organization: NexusAccountOrganization | null;
+  /** ISO time the token expires, when the server said so. */
+  expiresAt: string | null;
+  /** Absolute path of the credential store the token was written to. */
+  credentialsPath: string;
+  /** Non-fatal problems, e.g. the account lookup failed after a good login. */
+  warnings: string[];
+}
+
+/** Result of `cleo logout nexus`. */
+export interface NexusLogoutResult {
+  /** API origin the session belonged to. */
+  apiUrl: string;
+  /** `true` when a stored token existed and was deleted locally. */
+  removedLocally: boolean;
+  /**
+   * Server-side revocation outcome: `revoked` (the API ended the session),
+   * `already-invalid` (the API reported it was already gone), `failed`
+   * (network or server error: the local token is deleted anyway), or
+   * `skipped` (nothing was stored).
+   */
+  revocation: 'revoked' | 'already-invalid' | 'failed' | 'skipped';
+  /** Non-fatal problems. */
+  warnings: string[];
+}
+
+/**
+ * The binding of a local CLEO project to its Nexus registration, persisted in
+ * the project's machine-local `.cleo/nexus-link.json`, keyed by API origin.
+ */
+export interface NexusProjectLink {
+  /** API origin the project is registered with. */
+  apiUrl: string;
+  /** The local CLEO project id (the tracked `.cleo/project-id`). */
+  localProjectId: string;
+  /** The project id the server returned (the server keys projects by the CLEO id). */
+  remoteProjectId: string;
+  /** Owning organization id. */
+  organizationId: string;
+  /** Plaintext display-name label the server holds, or `null` when it has none. */
+  label: string | null;
+  /** Journal stream id for the project. */
+  streamId: string;
+  /** ISO time of the last successful link. */
+  linkedAt: string;
+}
+
+/** Result of `cleo project link`. */
+export interface NexusProjectLinkResult {
+  /** The persisted binding. */
+  link: NexusProjectLink;
+  /**
+   * `true` when the server already had this project id (HTTP 200; its label
+   * was updated to the one sent), `false` when this call registered it (201).
+   * Linking is idempotent either way.
+   */
+  alreadyLinked: boolean;
+  /** Absolute path of the local binding file. */
+  linkPath: string;
+}

package/src/operations/focus.ts

@@ -15,7 +15,7 @@
 import type {
   KnowledgeCoverage,
   KnowledgeDiagnostic,
-  KnowledgeHealth,
+  KnowledgeHealthSummary,
 } from '../knowledge-health.js';
 import type { MviDigest } from '../mvi.js';
 import type { AttentionScopeKind } from './attention.js';
@@ -195,8 +195,12 @@ export interface FocusBrainContext {
 export interface FocusShowResult {
   /** Assessed graph coverage; absence on legacy responses is not healthy coverage. */
   coverage?: KnowledgeCoverage;
-  /** Bounded deterministic maintenance and sourced repair findings for the foreground caller. */
-  knowledgeHealth?: KnowledgeHealth;
+  /**
+   * Bounded deterministic maintenance and sourced repair findings for the
+   * foreground caller. Its coverage is not repeated: `coverageRef` is
+   * `/coverage`, the single coverage object of this result (T12522).
+   */
+  knowledgeHealth?: KnowledgeHealthSummary;
   /** Failed auxiliary reads are distinct from successfully empty sources. */
   sourceDiagnostics?: Record<string, KnowledgeDiagnostic>;
   /** Core identity of the focused entity. */

package/src/operations/nexus-scope-map.ts

@@ -473,6 +473,15 @@ export const NEXUS_SCOPE_MAP = {
     stores: ['nexus-registry'],
     requiresProject: false,
   },
+  'projects.fleet': {
+    op: 'projects.fleet',
+    description:
+      'Fleet view: every project, where it lives on each device, and its last recorded git state (read-only).',
+    scope: 'global',
+    effect: 'read',
+    stores: ['nexus-registry'],
+    requiresProject: false,
+  },
   'projects.register': {
     op: 'projects.register',
     description: 'Register a project (alias: register).',