@cleocode/contracts 2026.9.22 → 2026.9.24

package/src/decide.ts

@@ -143,6 +143,17 @@ export interface DecisionRequest {
   readonly state: DecisionState;
   /** Question name → question (1–32 entries). Names key the answers in {@link DecisionOutcome}. */
   readonly questions: Readonly<Record<string, DecisionQuestion>>;
+  /**
+   * Language hint (e.g. `en`). Sent only to a provider whose capabilities
+   * include `langHint`; others never see it (T12664).
+   */
+  readonly lang?: string;
+  /**
+   * Provider-side answer cache. `false` asks a provider with `cacheControl`
+   * not to answer from its cache (real latency, sensitive text). Ignored by
+   * providers without the capability.
+   */
+  readonly cache?: boolean;
 }
 
 /** Answer to a {@link NoulDecisionQuestion}. */
@@ -196,14 +207,226 @@ export interface DecisionOutcome {
   readonly latencyMs: number;
   /** Provider-reported cost in US dollars, when known. */
   readonly costUsd?: number;
+  /** Provider-reported cost in integer micro-dollars, when known (T12664). */
+  readonly costMicros?: number;
+  /**
+   * Account balance in integer micro-dollars reported with this answer, when
+   * known. The Jev wire adapter never sets it (the layahost OpenAPI reports
+   * balance only via `GET /v1/usage`, T12715); other providers may.
+   */
+  readonly balanceMicros?: number;
+  /** Provider model checkpoint that answered, when reported. */
+  readonly checkpoint?: string;
   /** Provider-reported input-token count, when known. */
   readonly inputTokens?: number;
 }
 
+// ─── Provider kinds (T12713) ─────────────────────────────────────────────────
+
+/**
+ * Every supported decision-provider kind, recommended first.
+ *
+ * - `layahost` — the hosted provider at {@link LAYAHOST_BASE_URL}; the user
+ *   supplies only an API key.
+ * - `jev`      — any other Jev-compatible endpoint; the user supplies the URL.
+ */
+export const DECISION_PROVIDER_KINDS = ['layahost', 'jev'] as const;
+
+/** A decision-provider kind. See {@link DECISION_PROVIDER_KINDS}. */
+export type DecisionProviderKind = (typeof DECISION_PROVIDER_KINDS)[number];
+
+/** Base URL of the layahost API (its OpenAPI `servers[0].url`). */
+export const LAYAHOST_BASE_URL = 'https://layahost.com';
+
+/**
+ * Base URL of Jev's own API (TypeSafe AI). Source: the canonical spec
+ * `system-one-integration`, "Provider research: capability map" ("Jev itself
+ * (TypeSafe AI, `https://api.typesafe.ai`, OpenAPI v0.2.0)").
+ */
+export const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+
+/** layahost's routing model, the default for a layahost connection. */
+export const LAYAHOST_DEFAULT_MODEL = 'laya-auto';
+
+// ─── Named provider profiles (T12733) ────────────────────────────────────────
+
+/**
+ * A valid profile name: 1-32 characters of lowercase letters, digits and
+ * `-`, starting and ending with a letter or digit (e.g. `default`, `work`,
+ * `team-b`). A profile is addressed as `<provider>/<name>`, e.g.
+ * `layahost/default` or `jev/team`; one provider may hold several profiles
+ * (accounts), each with its own key.
+ */
+export const DECIDE_PROFILE_NAME_PATTERN = /^[a-z0-9](?:[a-z0-9-]{0,30}[a-z0-9])?$/;
+
+/** The profile name used when none is given: `<provider>/default`. */
+export const DECIDE_DEFAULT_PROFILE_NAME = 'default';
+
+/**
+ * The stored `baseUrl` of a profile that uses its provider's preset URL. It
+ * is resolved when the profile is used, so a changed preset URL flows
+ * through to every profile that kept the default.
+ */
+export const DECIDE_PROFILE_DEFAULT_URL = 'default';
+
+/** How a profile's base URL is set: the provider's preset URL, or an override. */
+export type DecideProfileUrlSource = 'default' | 'override';
+
+/**
+ * Reachability of a decision provider, as `GET /v1/models` reports it.
+ *
+ * - `reachable`         — the listing answered 2xx.
+ * - `unauthorized`      — the provider rejected the key.
+ * - `key_limit_reached` — the key's monthly decision limit is reached.
+ * - `unconfigured`      — no valid base URL + key stored.
+ * - `unreachable`       — network failure, timeout, or any other HTTP status.
+ */
+export type DecideProviderState =
+  | 'reachable'
+  | 'unauthorized'
+  | 'key_limit_reached'
+  | 'unconfigured'
+  | 'unreachable';
+
+/** Result of probing one profile (`cleo decide profiles --probe`). Secret-free. */
+export interface DecideProfileProbe {
+  /** Reachability verdict. */
+  readonly state: DecideProviderState;
+  /** HTTP status of the probe, when one was received. */
+  readonly httpStatus?: number;
+  /** Probe latency, ms. */
+  readonly latencyMs?: number;
+  /** Secret-free explanation, when there is one. */
+  readonly detail?: string;
+}
+
+/** One named System One provider profile, as listed. Carries no key, only its masked preview. */
+export interface DecideProfileSummary {
+  /** Profile id, `<provider>/<name>`, e.g. `layahost/work`. */
+  readonly id: string;
+  /** Profile name within its provider, e.g. `work`. */
+  readonly name: string;
+  /** Whether everyday decisions use this profile. Exactly one profile is active when any is. */
+  readonly active: boolean;
+  /** Whether the profile holds an acceptable base URL and a non-blank key. */
+  readonly configured: boolean;
+  /** Provider kind. */
+  readonly provider: DecisionProviderKind;
+  /** Resolved base URL (userinfo removed). */
+  readonly baseUrl: string;
+  /** Whether the URL is the provider's preset (`default`) or an override. */
+  readonly urlSource: DecideProfileUrlSource;
+  /** Default model, when stored. */
+  readonly model?: string;
+  /** Masked key preview (`…abcd`). */
+  readonly keyPreview: string;
+  /** ISO timestamp of the profile's last write, when known. */
+  readonly updatedAt?: string;
+  /** Reachability, when probed. */
+  readonly probe?: DecideProfileProbe;
+}
+
+/**
+ * A profile resolved for use (`resolveDecideProfile`): its id, provider, base
+ * URL (a stored `default` already resolved to the preset), plaintext API key
+ * and default model. Contains the key: pass it to the wire and never log or
+ * emit it. `profile` repeats `name` so the value can be used directly as a
+ * decision connection whose provider state is cached per profile.
+ */
+export interface DecideProfileConnection {
+  /** Profile id, `<provider>/<name>`. */
+  readonly name: string;
+  /** Same as {@link DecideProfileConnection.name}. */
+  readonly profile: string;
+  /** Provider kind. */
+  readonly provider: DecisionProviderKind;
+  /** Resolved base URL. */
+  readonly baseUrl: string;
+  /** Plaintext API key. SECRET. */
+  readonly apiKey: string;
+  /** Default model, when stored. */
+  readonly model?: string;
+}
+
+/** Result of listing the System One profiles. Secret-free. */
+export interface DecideProfileListResult {
+  /** Absolute path of the credential store. */
+  readonly path: string;
+  /** Id (`<provider>/<name>`) of the active profile, or `null` when none is configured. */
+  readonly active: string | null;
+  /** Every stored profile, sorted by id. */
+  readonly profiles: readonly DecideProfileSummary[];
+  /**
+   * True when the top-level settings disagreed with the active profile's
+   * entry (an older CLEO rewrote the file) and were taken as authoritative.
+   */
+  readonly reconciled: boolean;
+}
+
 /** Connection settings for a decision provider. */
 export interface DecisionProviderConfig {
   /** Absolute base URL of the provider's API (no trailing path to the endpoint). */
   readonly baseUrl: string;
+  /** Provider kind; absent means a custom Jev-compatible endpoint (`jev`). */
+  readonly provider?: DecisionProviderKind;
+}
+
+// ─── Provider capabilities (T12664) ──────────────────────────────────────────
+
+/**
+ * What a decision provider can do beyond the Jev minimum
+ * (`POST /v1/systemone`, 32 questions, 32,000-character state). A caller asks
+ * for a capability; the client degrades when it is absent (spec
+ * `system-one-integration` §2.2).
+ */
+export interface DecisionProviderCapabilities {
+  /** Wire protocol the provider speaks. */
+  readonly wire: string;
+  /** Most questions one request may carry. */
+  readonly maxQuestionsPerRequest: number;
+  /** Largest state, in characters. */
+  readonly maxStateChars: number;
+  /** Batch endpoint limits, when the provider has one. */
+  readonly batch?: { readonly maxRequests: number; readonly maxQuestions: number };
+  /** Built-in template names, when the provider has templates. */
+  readonly templates?: readonly string[];
+  /** Server-side flows are available. */
+  readonly flows?: boolean;
+  /** A usage/balance endpoint and cost headers are available. */
+  readonly usage?: boolean;
+  /** The request's `cache` field is honoured. */
+  readonly cacheControl?: boolean;
+  /** The request's `lang` field is honoured. */
+  readonly langHint?: boolean;
+  /** How the provider reports cost. */
+  readonly reportsCost?: 'micros' | 'usd' | false;
+}
+
+/** The Jev minimum every provider supports; the default when a provider reports nothing. */
+export const JEV_MINIMUM_CAPABILITIES: DecisionProviderCapabilities = {
+  wire: 'jev-systemone/1',
+  maxQuestionsPerRequest: 32,
+  maxStateChars: 32_000,
+  reportsCost: 'usd',
+};
+
+/** One item of a batch call: its outcome, or why it failed. */
+export type DecisionBatchItem =
+  | { readonly ok: true; readonly outcome: DecisionOutcome }
+  | { readonly ok: false; readonly status?: number; readonly errorKind: string };
+
+/** Account usage and balance as a provider reports it. */
+export interface DecisionProviderUsage {
+  /** Balance in integer micro-dollars. */
+  readonly balanceMicros?: number;
+  /** Decisions the balance still covers. */
+  readonly decisionsLeft?: number;
+  /** Plan name. */
+  readonly plan?: string;
+  /** End of the current plan period, ISO-8601. */
+  readonly periodEnd?: string;
+  /** Decisions and cost over the queried window. */
+  readonly totals?: { readonly decisions?: number; readonly costMicros?: number };
 }
 
 // ─── Zod schemas ──────────────────────────────────────────────────────────────
@@ -290,6 +513,11 @@ export const decisionQuestionSchema = z.discriminatedUnion('type', [
  */
 export const decisionRequestSchema = z.object({
   model: z.string().min(1).optional(),
+  lang: z
+    .string()
+    .regex(/^[a-z]{2,3}(-[A-Za-z0-9]{2,8})?$/)
+    .optional(),
+  cache: z.boolean().optional(),
   state: decisionStateSchema,
   questions: z.record(z.string().min(1), decisionQuestionSchema).refine(
     (questions) => {
@@ -346,10 +574,17 @@ export const decisionOutcomeSchema = z.object({
   requestId: z.string().min(1).optional(),
   latencyMs: z.number().nonnegative(),
   costUsd: z.number().nonnegative().optional(),
+  costMicros: z.number().int().nonnegative().optional(),
+  balanceMicros: z.number().int().optional(),
+  checkpoint: z.string().min(1).optional(),
   inputTokens: z.number().int().nonnegative().optional(),
 });
 
+/** Zod schema for {@link DecisionProviderKind}. */
+export const decisionProviderKindSchema = z.enum(DECISION_PROVIDER_KINDS);
+
 /** Zod schema for {@link DecisionProviderConfig}; `baseUrl` must be an absolute URL. */
 export const decisionProviderConfigSchema = z.object({
   baseUrl: z.url(),
+  provider: decisionProviderKindSchema.optional(),
 });

package/src/dispatch/operations-registry.ts

@@ -814,12 +814,22 @@ export const OPERATIONS: OperationDef[] = [
     gateway: 'query' as const,
     domain: 'tasks' as const,
     operation: 'history',
-    description: 'Show task work history (time tracked per task)',
+    description:
+      'Show task work history; with taskId, the task audit trail; with ranking, who changed its priority/severity/kind/depends and why (T12693)',
     tier: 1,
     idempotent: true,
     sessionRequired: false,
     requiredParams: [],
-    params: [],
+    params: [
+      { name: 'taskId', type: 'string', required: false, description: 'Task to show history for' },
+      { name: 'limit', type: 'number', required: false, description: 'Maximum entries' },
+      {
+        name: 'ranking',
+        type: 'boolean',
+        required: false,
+        description: 'Only ranking-input changes (actor, session, reason, before/after)',
+      },
+    ] satisfies ParamDef[],
   },
   {
     gateway: 'query',
@@ -3062,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[],
   },
   {
@@ -3364,6 +3382,33 @@ export const OPERATIONS: OperationDef[] = [
     ] satisfies ParamDef[],
     outputSchema: OUTPUT_CONTRACTS['tasks.assignee'],
   },
+  {
+    gateway: 'mutate',
+    domain: 'tasks',
+    operation: 'ranking.revert',
+    description:
+      'tasks.ranking.revert (mutate) — undo one recorded ranking change (priority/severity/kind/depends) as a new audited change (T12693, D11161)',
+    tier: 1,
+    idempotent: false,
+    sessionRequired: false,
+    requiredParams: ['entryId'],
+    params: [
+      {
+        name: 'entryId',
+        type: 'string',
+        required: true,
+        description: 'ranking_changed audit row id (cleo history ranking <taskId>)',
+        cli: { positional: true },
+      },
+      { name: 'reason', type: 'string', required: false, description: 'Why it is reverted' },
+      {
+        name: 'force',
+        type: 'boolean',
+        required: false,
+        description: 'Revert even though a field changed again since',
+      },
+    ] satisfies ParamDef[],
+  },
   {
     gateway: 'mutate',
     domain: 'tasks',
@@ -3711,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,
@@ -3724,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[],
   },
   {
@@ -3832,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',
@@ -3847,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)",
       },
     ],
   },
@@ -3856,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,
@@ -3868,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)",
+      },
     ],
   },
   {
@@ -4127,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)
@@ -6870,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/evidence-atom-schema.ts

@@ -500,6 +500,9 @@ export const GATE_EVIDENCE_REQUIREMENTS: Readonly<
       ['decision', 'files'],
       ['decision', 'note'],
       ['pr', 'files'],
+      // T12689: a deletion-only PR (no bytes to hash). Contextual validation
+      // accepts this only when every change the PR made is a deletion.
+      ['pr', 'note'],
     ],
   },
   testsPassed: { oneOf: [['test-run'], ['tool'], ['ci']] },

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,