@cleocode/contracts 2026.9.23 → 2026.9.25

package/src/branch-lock.ts

@@ -111,8 +111,50 @@ export interface WorktreeMergeResult {
    *
    * Callers should treat `nothingToIntegrate: true` as success-with-no-work,
    * and reserve failure handling for `merged: false` WITHOUT this flag.
+   *
+   * T12773: also set when {@link WorktreeMergeResult.landedUpstream} is true —
+   * the task branch already landed on `origin/<targetBranch>`, so there is no
+   * local integration left to do.
    */
   nothingToIntegrate?: boolean;
+  /**
+   * True when the `task/<taskId>` branch had **already landed upstream** — its
+   * tip is an ancestor of `origin/<targetBranch>`, or merging it into
+   * `origin/<targetBranch>` would change nothing (squash-merged PR).
+   *
+   * @remarks
+   * T12773: `cleo done --pr <n>` on a task whose PR had already merged on
+   * origin ran a local `git merge --no-ff task/<id>` into a stale local
+   * default branch, forking it from origin. When this flag is set no local
+   * merge was attempted and the operator's checkout was NOT moved; when the
+   * local default branch is behind, {@link WorktreeMergeResult.syncCommand}
+   * names the command to sync it (hint-only).
+   *
+   * Not set for a task branch with zero commits beyond the local default
+   * branch — that is plain `nothingToIntegrate`.
+   */
+  landedUpstream?: boolean;
+  /**
+   * True when the local merge was REFUSED because the local default branch is
+   * behind `origin/<targetBranch>` (or diverged from it: behind and ahead). A
+   * merge there would fork it from origin (T12773). The worktree and task
+   * branch are preserved; sync the default branch
+   * ({@link WorktreeMergeResult.syncCommand}) and re-run the integration.
+   */
+  staleTarget?: boolean;
+  /**
+   * Exact shell command that syncs the local default branch with
+   * `origin/<targetBranch>` — `git merge --ff-only` when it is only behind,
+   * a plain `git merge origin/<targetBranch>` when it is diverged (never a
+   * rebase, which would drop the local ADR-062 `--no-ff` task merge commits
+   * and rewrite agent SHAs). CLEO never runs it (T12773).
+   */
+  syncCommand?: string;
+  /**
+   * Operator-facing next step when integration was skipped or refused without
+   * a merge (T12773) — e.g. how to sync a stale local default branch.
+   */
+  hint?: string;
 }
 
 /**
@@ -366,6 +408,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 +570,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 +660,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 +707,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;
 }
 
 /**
@@ -180,6 +193,14 @@ export interface AcRow {
   updatedAt: string | null;
   /** Optional sha256(text) snapshot; writers MAY populate, readers MUST treat null as "unknown". */
   contentHash: string | null;
+  /**
+   * Row uid (T12341): the criterion's identity across devices and across edits
+   * (`id` changes with the text; `uid` does not). `null` until the store fills
+   * it; absent from accessors that predate it.
+   */
+  uid?: string | null;
+  /** Birth fingerprint (T12341): write-once, carried with the uid across edits. */
+  birthFp?: string | null;
 }
 
 /** Machine-readable AC child-projection drift codes for doctor/audit output. */
@@ -251,6 +272,12 @@ export interface AcBindingRow {
   bindingType: 'direct' | 'satisfies' | 'coverage';
   /** ISO-8601 timestamp of binding creation. */
   createdAt: string;
+  /**
+   * The evidence was recorded against a different text of this criterion
+   * (T12341): the criterion kept its identity through an edit, but no gate may
+   * count this binding until the evidence is re-verified. Absent means valid.
+   */
+  stale?: boolean;
 }
 
 /** Query options for bounded reads from the append-only task audit log. @task T10594 */
@@ -281,16 +308,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 +475,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>;
@@ -334,6 +515,10 @@ export interface TransactionAccessor {
       targetTaskId?: string | null;
       projection?: string;
       contentHash?: string | null;
+      /** Row uid to keep (T12341); omitted → a new uid is minted. */
+      uid?: string | null;
+      /** Birth fingerprint to keep with the uid (T12341). */
+      birthFp?: string | null;
     }>,
   ): Promise<void>;
   /**
@@ -349,13 +534,48 @@ export interface TransactionAccessor {
    * @task T10508
    */
   deleteAcRowsForTask(taskId: string): Promise<void>;
+  /**
+   * Delete only the named AC rows of `taskId` (rows of other tasks are never
+   * touched). Used by the diff apply path so ACs that survive an edit keep
+   * their row — and therefore their evidence bindings.
+   *
+   * `keepBindingsForUids`: uids the same write carries onto new rows (an
+   * edited criterion keeps its uid, T12341); their bindings are kept, as
+   * stale evidence, instead of pruned.
+   * @task T12789
+   */
+  deleteAcRowsByIds(
+    taskId: string,
+    ids: readonly string[],
+    keepBindingsForUids?: readonly string[],
+  ): Promise<void>;
+  /**
+   * Update existing AC rows of their own task in place, keyed by `(id, taskId)`.
+   * Every mutable column is rewritten from the supplied row; `id` and
+   * `taskId` are never changed. A row that does not exist for that task is
+   * an error, never an insert.
+   * @task T12789
+   */
+  updateAcRows(
+    rows: Array<{
+      id: string;
+      taskId: string;
+      ordinal: number;
+      text: string;
+      kind?: 'text' | 'child_task' | 'evidence_bound';
+      sourceKey?: string;
+      targetTaskId?: string | null;
+      projection?: string;
+      contentHash?: string | null;
+    }>,
+  ): Promise<void>;
   /**
    * Append a history row to `task_acceptance_criteria_history` capturing the
    * AC text that is about to be superseded.
    * @task T10508
    */
   appendAcHistory(
-    rows: Array<{ acId: string; previousText: string; reason: string }>,
+    rows: Array<{ acId: string; previousText: string; reason: string; acUid?: string | null }>,
   ): Promise<void>;
   /**
    * Read all `evidence_ac_bindings` rows whose `ac_id` ∈ the given set.
@@ -387,6 +607,16 @@ export interface TransactionAccessor {
       bindingType: 'direct' | 'satisfies' | 'coverage';
     }>,
   ): Promise<void>;
+  /**
+   * Delete every `evidence_ac_bindings` row whose `ac_id` names no AC row
+   * (bindings left behind before AC removal pruned them), recording each
+   * removed row in the task audit log (`ac.bindings.pruned`) first. Backs
+   * `cleo doctor ac-bindings --fix`.
+   *
+   * @returns the removed bindings
+   * @task T12790
+   */
+  pruneOrphanAcBindings(): Promise<AcBindingRow[]>;
 }
 
 // Re-export AcRow at the module level for both transaction + outer accessor use.
@@ -436,6 +666,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>;
 
@@ -471,6 +708,14 @@ export interface DataAccessor {
    */
   getAcBindings(acIds: readonly string[]): Promise<AcBindingRow[]>;
 
+  /**
+   * Read every `evidence_ac_bindings` row whose `ac_id` names no row of
+   * `task_acceptance_criteria` — a binding for an AC that no longer exists.
+   * Read-only; backs `cleo doctor ac-bindings`.
+   * @task T12790
+   */
+  findOrphanAcBindings(): Promise<AcBindingRow[]>;
+
   // ---- Metadata (schema_meta KV store) ----
 
   /** Read a typed value from the metadata store. Returns null if not found. */
@@ -579,29 +824,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.
-   *
-   * No-op if the task is not currently claimed.
+   * Release the claim lease on a task. Without `force`, only the holder
+   * session's lease is cleared; with `force` any lease is cleared.
    *
-   * @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). */