@cleocode/contracts 2026.9.23 → 2026.9.24

package/src/branch-lock.ts

@@ -366,6 +366,19 @@ export const ISOLATION_ENV_KEYS = [
 /** Union of all isolation env key strings. */
 export type IsolationEnvKey = (typeof ISOLATION_ENV_KEYS)[number];
 
+/**
+ * The identity keys re-exported on every shell call of a spawned agent
+ * (T12502) — see {@link IsolationResult.perCallLine}. `CLEO_AGENT_ROLE` is
+ * among them because the git shim reads it on every `git` call to enforce
+ * the worker's restricted-role policy; a shell that lost it would run git
+ * unrestricted.
+ */
+const IDENTITY_ENV_KEYS = [
+  'CLEO_SESSION_ID',
+  'CLEO_AGENT_ID',
+  'CLEO_AGENT_ROLE',
+] as const satisfies readonly IsolationEnvKey[];
+
 /**
  * Absolute-path validation rules enforced for Edit/Write SDK tool operations.
  *
@@ -515,6 +528,15 @@ export interface IsolationResult {
    * The trailing newline is included so callers can concatenate directly.
    */
   preamble: string;
+  /**
+   * The one line an agent must run at the start of EVERY shell call (T12502):
+   * `cd <worktree> && export CLEO_SESSION_ID=… CLEO_AGENT_ID=… CLEO_AGENT_ROLE=… || exit 1`
+   * (identity keys only when set; every value shell-quoted). Harness shells
+   * keep neither cwd nor env between calls, so this line re-enters the
+   * worktree AND re-binds the agent's own session and the role the git shim
+   * enforces. It is also Step 1 of {@link IsolationResult.preamble}.
+   */
+  perCallLine: string;
   /**
    * Boundary contract for downstream enforcement layers (git-shim, tests).
    *
@@ -596,11 +618,24 @@ export function provisionIsolatedShell(options: IsolationOptions): IsolationResu
   // T12520 — every path is emitted through `shellQuote`, never interpolated
   // bare or inside double quotes, so the snippet parses for any worktree path.
   const quotedPath = shellQuote(worktreePath);
+  // T12502 — env does not persist between an agent harness's Bash calls, so
+  // the per-call line re-binds the agent's own identity (and the role the git
+  // shim enforces) along with the cwd.
+  // Without it a worker's `cleo start` resolves to the ORCHESTRATOR's session
+  // and is refused on its own (spawn-claimed) task with E_TASK_CLAIMED.
+  const identityExports = IDENTITY_ENV_KEYS.filter((k) => env[k] !== '').map(
+    (k) => `${k}=${shellQuote(env[k])}`,
+  );
+  const perCallLine =
+    identityExports.length > 0
+      ? `cd ${quotedPath} && export ${identityExports.join(' ')} || exit 1`
+      : `cd ${quotedPath} || exit 1`;
   const preamble = [
     '## Worktree Isolation (REQUIRED — do not skip)',
     '',
-    '# Step 1: Enter the worktree (exits immediately if path is missing)',
-    `cd ${quotedPath} || exit 1`,
+    '# Step 1: Enter the worktree and bind your session (exits if the path is missing).',
+    '# Repeat this line at the start of EVERY Bash call: cwd and env do not persist.',
+    perCallLine,
     '',
     '# Step 2: Verify working directory (guards against shell/symlink quirks)',
     'case "$PWD" in',
@@ -630,7 +665,7 @@ export function provisionIsolatedShell(options: IsolationOptions): IsolationResu
     absolutePathRules,
   };
 
-  return { cwd, env, preamble, boundaryContract };
+  return { cwd, env, preamble, perCallLine, boundaryContract };
 }
 
 // ---------------------------------------------------------------------------

package/src/data-accessor.ts

@@ -17,6 +17,7 @@ import type { ArchivedTask } from './archive.js';
 import type { Session } from './session.js';
 import type {
   Task,
+  TaskClaim,
   TaskKind,
   TaskPriority,
   TaskSeverity,
@@ -150,6 +151,18 @@ export interface TaskFieldUpdates {
   updatedAt?: string | null;
   assignee?: string | null;
   pipelineStage?: string | null;
+  /**
+   * Agent claim lease columns (T12502). Change them through
+   * `DataAccessor.claimTask` / `unclaimTask`, which pair them with a
+   * {@link TaskClaimGuard} so the write is a compare-and-set on the holder.
+   */
+  claimedBySession?: string | null;
+  /** Agent identity of the lease holder (T12502). */
+  claimedByAgent?: string | null;
+  /** ISO-8601 UTC instant the lease was taken (T12502). */
+  claimedAt?: string | null;
+  /** ISO-8601 UTC instant the lease lapses unless renewed (T12502). */
+  leaseExpiresAt?: string | null;
 }
 
 /**
@@ -281,16 +294,165 @@ export interface TaskAuditLogRow {
  * Optimistic-concurrency guard for a single-task write (T12503).
  *
  * A task's version is its `updatedAt` timestamp (falling back to `createdAt`
- * for a row that was never updated). Writers keep it strictly increasing, so a
- * caller that read version `v` and passes `expectedUpdatedAt: v` either writes
- * against exactly the row it read or fails with `E_CONFLICT`
- * (`ExitCode.VERSION_CONFLICT`) carrying the current version. The comparison
+ * for a row that was never updated). The update, complete and field-update
+ * paths advance it strictly, so a caller that read version `v` and passes
+ * `expectedUpdatedAt: v` either writes against exactly the row it read or
+ * fails with `E_CONFLICT` (`ExitCode.VERSION_CONFLICT`) carrying the current
+ * version. Some other writers still stamp it from the clock, leaving a narrow
+ * same-millisecond window (T12720). The comparison
  * runs inside the write transaction, after `BEGIN IMMEDIATE` holds the lock.
  * Omitting the guard keeps last-writer-wins semantics.
  */
 export interface TaskWriteGuard {
   /** Version the caller read; the write fails with `E_CONFLICT` if the row moved on. */
   expectedUpdatedAt?: string;
+  /**
+   * The task as the caller read it. Used only to build the conflict summary:
+   * on `E_CONFLICT`, the fields whose stored value differs from this snapshot
+   * are reported in {@link TaskConflictDetails.changedFields}. @task T12503
+   */
+  baseline?: Task;
+  /**
+   * Compare-and-set on the claim lease columns (T12502). The write matches
+   * only while the stored holder satisfies {@link TaskClaimGuard.mode}; when
+   * it does not, the write fails with `E_TASK_CLAIMED`
+   * ({@link TaskClaimedDetails}) instead of `E_CONFLICT`.
+   */
+  claim?: TaskClaimGuard;
+  /**
+   * Leave the task version (`updatedAt`) unchanged. For lease bookkeeping
+   * (renew, release) that must not invalidate another writer's `--if-match`.
+   * @task T12502
+   */
+  keepVersion?: boolean;
+}
+
+/**
+ * How a claim write treats the lease already stored on the task (T12502).
+ *
+ * - `acquire`: succeeds when the task is unclaimed, already held by the
+ *   caller's session, or held by `handoffFrom` (an orchestrator handing the
+ *   task to the agent it spawns). An expired lease still blocks: taking it is
+ *   explicit.
+ * - `take-over`: `acquire`, or the stored lease has expired. Audited.
+ * - `force`: unconditional, even over a live lease. Audited.
+ * - `renew`: only the holder session may extend its lease.
+ * - `release`: only the holder session may clear its lease.
+ */
+export type TaskClaimMode = 'acquire' | 'take-over' | 'force' | 'renew' | 'release';
+
+/**
+ * Claim predicate for a guarded task write (T12502). Evaluated in the
+ * UPDATE's WHERE clause, inside the write transaction.
+ */
+export interface TaskClaimGuard {
+  /** The caller's session, or `null` for an unbound caller (holds no lease). */
+  sessionId: string | null;
+  /** Which stored holders the write may replace. */
+  mode: TaskClaimMode;
+  /** ISO-8601 UTC "now" used for the lease-expiry comparison. */
+  now: string;
+  /** A session whose live lease `acquire` may take over (spawn hand-off). */
+  handoffFrom?: string | null;
+}
+
+/**
+ * A request to take, renew or override the claim lease on a task (T12502).
+ */
+export interface TaskClaimRequest {
+  /** The claiming session; `null` checks the claim without taking a lease. */
+  sessionId: string | null;
+  /** Agent identity recorded with the lease, or `null`. */
+  agentId: string | null;
+  /** How to treat a stored lease (see {@link TaskClaimMode}); never `release`. */
+  mode: Exclude<TaskClaimMode, 'release'>;
+  /** Lease length in milliseconds; defaults to the core lease TTL. */
+  leaseMs?: number;
+  /** Clock override (ISO-8601 UTC) for tests. */
+  now?: string;
+  /** A session whose live lease `acquire` may take over (spawn hand-off). */
+  handoffFrom?: string | null;
+}
+
+/**
+ * `details` of an `E_TASK_CLAIMED` (`ExitCode.TASK_CLAIMED`) error: who holds
+ * the task, until when, and which explicit, audited override applies.
+ *
+ * @task T12502
+ */
+export interface TaskClaimedDetails {
+  /** Always `'claimedBySession'`: the lease-holder column the claim compared. */
+  field: 'claimedBySession';
+  /** The claimed task. */
+  taskId: string;
+  /** The lease currently stored on the task. */
+  holder: TaskClaim;
+  /** `true` when the holder's lease has lapsed (take it with `--take-over`). */
+  expired: boolean;
+  /** The refused caller. */
+  requester: { sessionId: string | null; agentId: string | null };
+  /** The flag that would override: `--take-over` (expired) or `--force-claim` (live). */
+  override: '--take-over' | '--force-claim';
+}
+
+/**
+ * One field that differs between the caller's read and the stored row, as
+ * reported on an `E_CONFLICT` error. Values are JSON-serialised and truncated
+ * so the envelope stays small; `null` means the field was absent.
+ *
+ * @task T12503
+ */
+export interface TaskConflictChange {
+  /** Task field name (camelCase, as on {@link Task}). */
+  field: string;
+  /** JSON of the value in the caller's read, or `null` when absent. */
+  was: string | null;
+  /** JSON of the value currently stored, or `null` when absent. */
+  now: string | null;
+}
+
+/**
+ * `details` of an `E_CONFLICT` (`ExitCode.VERSION_CONFLICT`) task error: the
+ * version the caller expected, the version now stored, and which fields moved
+ * so an agent can re-read, merge and retry with `--if-match <currentVersion>`.
+ *
+ * `changedFields` is diffed against the caller's read when the write path
+ * holds it (`cleo update`, `cleo complete`, or a guard with `baseline`). When
+ * the caller's read was already older than the one this command made, the
+ * summary covers only changes after that read; `current` always carries the
+ * stored values to merge against.
+ *
+ * @task T12503
+ */
+export interface TaskConflictDetails {
+  /** Always `'updatedAt'`: the version field. */
+  field: 'updatedAt';
+  /** The version the caller expected. */
+  expected: string;
+  /** The version currently stored (same as {@link currentVersion}). */
+  actual: string;
+  /** The version to pass as `--if-match` after merging. */
+  currentVersion: string;
+  /** Names of the fields that differ between the caller's read and the stored row. */
+  changedFields: string[];
+  /** Per-field before/after summary for {@link changedFields}. */
+  changes: TaskConflictChange[];
+  /**
+   * Merge-relevant stored values of the task right now, bounded so the
+   * envelope stays small: `title` is cut at 200 characters and `labels` /
+   * `depends` hold at most the first 50 entries, with the full counts in
+   * `labelsTotal` / `dependsTotal`.
+   */
+  current: {
+    title: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    labels: string[];
+    labelsTotal: number;
+    depends: string[];
+    dependsTotal: number;
+    parentId: string | null;
+  } | null;
 }
 
 /**
@@ -299,6 +461,11 @@ export interface TaskWriteGuard {
  */
 export interface TransactionAccessor {
   upsertSingleTask(task: Task): Promise<void>;
+  /**
+   * Insert a NEW task; never overwrites. Throws `ID_COLLISION` when the id is
+   * already stored (T12724).
+   */
+  insertNewTask(task: Task): Promise<void>;
   archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
   removeSingleTask(taskId: string): Promise<void>;
   setMetaValue(key: string, value: unknown): Promise<void>;
@@ -436,6 +603,13 @@ export interface DataAccessor {
   /** Upsert a single task (targeted write, no full-file reload). */
   upsertSingleTask(task: Task): Promise<void>;
 
+  /**
+   * Insert a NEW task under a freshly allocated or computed id. Never
+   * overwrites: throws `ID_COLLISION` when the id is already stored, and
+   * writes nothing (T12724).
+   */
+  insertNewTask(task: Task): Promise<void>;
+
   /** Archive a single task by ID (sets status='archived' + archive metadata). */
   archiveSingleTask(taskId: string, fields: ArchiveFields): Promise<void>;
 
@@ -579,29 +753,50 @@ export interface DataAccessor {
   /** Get a single agent instance by ID. Returns null if not found. */
   getAgentInstance(agentId: string): Promise<DataAccessorAgentInstance | null>;
 
-  // ---- Agent task claiming ----
+  // ---- Agent task claiming (leased, T12502) ----
 
   /**
-   * Atomically claim a task for an agent.
+   * Take, renew or override the claim lease on a task in one compare-and-set
+   * write (`updateTaskFields` with a {@link TaskClaimGuard}). The human
+   * `assignee` is never touched.
    *
-   * Uses `UPDATE ... WHERE assignee IS NULL OR assignee = agentId` to prevent
-   * race conditions. Throws if the task is already claimed by a different agent.
+   * With `sessionId: null` no lease is written; the call only verifies, in
+   * the same way, that no other session holds the task.
    *
    * @param taskId - ID of the task to claim.
-   * @param agentId - Agent identifier claiming the task.
-   * @throws {Error} When the task is not found or is already claimed by another agent.
+   * @param request - Claimant, mode and lease length.
+   * @returns The lease now held, or `null` when `sessionId` is `null`.
+   * @throws {Error} When the task is not found.
+   * @throws CleoError `E_TASK_CLAIMED` with {@link TaskClaimedDetails} when
+   *   another session holds the task and `mode` does not allow replacing it.
    */
-  claimTask(taskId: string, agentId: string): Promise<void>;
+  claimTask(taskId: string, request: TaskClaimRequest): Promise<TaskClaim | null>;
 
   /**
-   * Release a claimed task, clearing its assignee.
+   * Release the claim lease on a task. Without `force`, only the holder
+   * session's lease is cleared; with `force` any lease is cleared.
    *
-   * No-op if the task is not currently claimed.
-   *
-   * @param taskId - ID of the task to unclaim.
+   * @param taskId - ID of the task to release.
+   * @param release - The releasing session and whether to force.
+   * @returns `true` when a lease was cleared, `false` when there was none to clear.
    * @throws {Error} When the task is not found.
+   * @throws CleoError `E_TASK_CLAIMED` when another session holds the lease and `force` is not set.
+   */
+  unclaimTask(
+    taskId: string,
+    release: { sessionId: string | null; force?: boolean },
+  ): Promise<boolean>;
+
+  /**
+   * Heartbeat: extend every lease held by `sessionId` to `leaseExpiresAt`,
+   * without changing any task version (T12502). A session holding no lease
+   * costs one indexed read and takes no write lock.
+   *
+   * @param sessionId - The holder session.
+   * @param leaseExpiresAt - New lease expiry (ISO-8601 UTC).
+   * @returns Number of leases renewed.
    */
-  unclaimTask(taskId: string): Promise<void>;
+  renewSessionClaims(sessionId: string, leaseExpiresAt: string): Promise<number>;
 }
 
 // Factory functions (createDataAccessor, getTaskAccessor) live in @cleocode/core,

package/src/decide.ts

@@ -209,7 +209,11 @@ export interface DecisionOutcome {
   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. */
+  /**
+   * 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;
@@ -234,9 +238,131 @@ 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). */