@cleocode/contracts 2026.8.2 → 2026.8.4

package/src/collection-keys.ts

@@ -0,0 +1,45 @@
+/**
+ * The keys under which CLEO payloads carry a list of records.
+ *
+ * ## Why this is a shared constant (T12077)
+ *
+ * Different operations name their collection differently — `tasks.list` emits
+ * `tasks`, the SDK's generic list emits `items`, `tasks.find` emits `results`,
+ * and `tasks.next` emits `suggestions`. Each consumer that wants "the rows"
+ * has historically inlined its own guess, and each wrong guess fails SILENTLY,
+ * because an absent key is indistinguishable from an empty result set.
+ *
+ * Three separate outages traced to exactly this:
+ *
+ * 1. **T12067** — `output-mode.ts` knew only `tasks`/`items`, in three
+ *    separately-inlined lists. `cleo find … --output count` reported 1626
+ *    while `--output id` reported `No ids.` against the same payload.
+ * 2. **T12077 (this)** — `cleo next --output id` / `--output count` reported
+ *    nothing and zero while the envelope held 836 candidates, because
+ *    `suggestions` was in nobody's list.
+ * 3. **T12077 (the severe one)** — `defaultPickTask` in the sentient loop read
+ *    `response.data.tasks` from `cleo.tasks.find()`, which returns
+ *    `{results, total}` *unwrapped*. The key was wrong AND the `data` envelope
+ *    it was reaching through does not exist on the SDK surface, so
+ *    `allCandidates` was **always `[]`**. The autonomous loop therefore
+ *    returned `no-task` on every tick it had ever run — 24 ticks, 0 tasks
+ *    picked, across three months — and looked exactly like "there is no work
+ *    to do" rather than like a bug.
+ *
+ * The lesson those three share is that this list must exist in ONE place that
+ * both the render layer and the SDK consumers import. Adding an operation with
+ * a new collection key now means adding it here, once.
+ *
+ * @task T12077
+ */
+
+/**
+ * Collection keys in resolution order.
+ *
+ * Order matters only when a payload carries more than one (it should not);
+ * earlier keys win, which keeps the canonical `tasks` shape authoritative.
+ */
+export const COLLECTION_KEYS = ['tasks', 'items', 'results', 'suggestions'] as const;
+
+/** A key under which a payload may carry its rows. */
+export type CollectionKey = (typeof COLLECTION_KEYS)[number];

package/src/dispatch/operations-registry.ts

@@ -8392,6 +8392,28 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Commit plan file before dispatching',
       },
+      // T12089: the plan SCOPE. The workflow regenerates the plan when no
+      // committed plan is supplied, and `cleo release plan` requires
+      // `--saga | --epic | --tasks` — so without one of these the dispatched
+      // run dies at "Prepare bump-PR" after a fully green preflight.
+      //
+      // A param absent from this registry is STRIPPED before the domain handler
+      // sees it, silently. `--tasks` was accepted by the CLI, forwarded by the
+      // handler and by `releaseOpen`, and still arrived empty at the workflow
+      // because this declaration was the fourth hop in the chain.
+      {
+        name: 'epic',
+        type: 'string',
+        required: false,
+        description: 'Epic task ID forwarded as the plan scope (e.g. T9999)',
+      },
+      {
+        name: 'tasks',
+        type: 'string',
+        required: false,
+        description:
+          'Comma-separated task IDs forwarded as the plan scope for a task-scoped release',
+      },
     ] satisfies ParamDef[],
   },
 

package/src/index.ts

@@ -2666,3 +2666,5 @@ export {
   CAAMP_MARKER_END,
   CAAMP_MARKER_START,
 } from './caamp-markers.js';
+// T12077: SSoT for the keys under which payloads carry their rows.
+export { COLLECTION_KEYS, type CollectionKey } from './collection-keys.js';

package/src/llm/system-resolver.ts

@@ -124,6 +124,16 @@ export interface ResolveLLMForSystemOptions {
    * without changing the system identity.
    */
   roleOverride?: RoleName;
+  /**
+   * Providers to skip for this resolution (T12084).
+   *
+   * Mirrors `ResolveLLMForRoleOptions.excludeProviders` and exists for the same
+   * reason: a caller that has just watched a provider fail needs its retry to
+   * land elsewhere. Without it, every consumer of this resolver — fix-gen among
+   * them — is permanently pinned to the first provider the selector picks, no
+   * matter how reliably it fails.
+   */
+  excludeProviders?: readonly string[];
 
   /**
    * When `true`, the resolver skips the provider-registry defaultModel lookup

package/src/operations/llm.ts

@@ -164,7 +164,9 @@ export type CredentialSourceWire =
   | 'cred-file'
   | 'claude-creds'
   | 'global-config'
-  | 'project-config';
+  | 'project-config'
+  /** Keyless local inference daemon detected at runtime (T12082). */
+  | 'local-daemon';
 
 /**
  * Authentication scheme used when sending the credential to the provider.
@@ -223,6 +225,22 @@ export interface CredentialMetadataWire {
   source: CredentialSourceWire | undefined;
   /** Scheme used to present the credential to the provider. */
   authType: AuthTypeWire;
+  /**
+   * Custom API endpoint this credential targets, when it has one.
+   *
+   * NOT a secret — an endpoint URL — so it belongs on the metadata wire rather
+   * than behind the sealed handle. It is load-bearing: without it a consumer
+   * building a transport cannot learn that a credential points at a local or
+   * proxied endpoint, and silently falls back to the vendor's public API.
+   *
+   * T12081: `role-executor` set `baseUrl` from `deriveApiWire(provider)` — the
+   * provider DEFAULT — because this field did not exist. An Ollama credential
+   * carrying `http://localhost:11434/v1` was rewritten to `api.openai.com` and
+   * rejected 401; the same held for LM Studio, vLLM, OpenRouter and Azure.
+   * Every custom-endpoint credential resolved correctly, then called the wrong
+   * host.
+   */
+  baseUrl?: string | null;
 }
 
 // ============================================================================
@@ -365,6 +383,19 @@ export interface ResolveLLMForRoleOptions {
    * @task T11759
    */
   profileOverride?: string;
+  /**
+   * Providers to skip during this resolution (T12082).
+   *
+   * Set by the caller after a provider has already failed for this call, so
+   * the retry lands somewhere else. Applies to EVERY tier including config
+   * pins: a pinned provider that just returned a terminal error is not a
+   * better answer for having been pinned.
+   *
+   * Empty/absent leaves resolution completely unchanged.
+   *
+   * @task T12082
+   */
+  excludeProviders?: readonly string[];
 }
 
 // ============================================================================

package/src/spawn-types.ts

@@ -18,6 +18,15 @@ export type Provider = string;
  * CAAMP-compatible spawn options (inlined for zero-dep contracts).
  */
 export interface CAAMPSpawnOptions {
+  /**
+   * Capacity-aware routing hint — the id of the least-loaded registered agent
+   * (Wave 6-C/D). Declared explicitly because `spawn-ops.ts` both writes it
+   * and reads it back for the `SubagentStart`/`SubagentStop` payloads; under
+   * the bare index signature it resolved to `unknown`, so
+   * `options?.preferredAgent ?? \`worker-${taskId}\`` widened to `{}` and the
+   * agentId silently lost its type. @task T12071
+   */
+  preferredAgent?: string;
   [key: string]: unknown;
 }
 
@@ -79,6 +88,17 @@ export interface CLEOSpawnResult extends CAAMPSpawnResult {
     durationMs?: number;
   };
 
+  /**
+   * Terminal (or in-flight) state of the spawned agent.
+   *
+   * Declared explicitly because `spawn-ops.ts` reads `result.status` to build
+   * the `SubagentStop` hook payload. Inherited from `CAAMPSpawnResult`'s bare
+   * `[key: string]: unknown` it resolved to `unknown`, so the value flowed
+   * into a typed payload field unchecked — and it does not even share that
+   * field's vocabulary ('completed' here vs 'complete' there). @task T12071
+   */
+  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+
   /** Reference to manifest entry if output was captured */
   manifestEntryId?: string;
 }

package/src/task.ts

@@ -192,7 +192,23 @@ export type EvidenceAtom =
       failCount: number;
       skipCount: number;
     }
-  | { kind: 'tool'; tool: string; exitCode: number; stdoutTail: string }
+  | {
+      kind: 'tool';
+      tool: string;
+      exitCode: number;
+      stdoutTail?: string;
+      /**
+       * The project has no such toolchain, so the gate is satisfied by absence
+       * rather than by a run (T12083).
+       *
+       * Recorded explicitly so the audit trail never implies a tool ran that
+       * did not. Only ever set for a GUESSED language default — a command
+       * declared in `project-context.json` is always executed.
+       */
+      notApplicable?: boolean;
+      /** Why the tool was judged inapplicable. Present iff `notApplicable`. */
+      reason?: string;
+    }
   | { kind: 'url'; url: string }
   | { kind: 'note'; note: string }
   | { kind: 'override'; reason: string }