@cleocode/contracts 2026.6.11 → 2026.6.13

package/src/__tests__/operation-def.test.ts

@@ -102,7 +102,8 @@ describe('dispatch/operation-def contracts', () => {
     expect(CANONICAL_DOMAINS.length).toBeGreaterThan(0);
     // T9954 — snapshot the current count so accidental additions/removals
     // trip this test and force an explicit human review.
-    expect(CANONICAL_DOMAINS.length).toBe(23);
+    // T11889-D — +1 for the new 'selfimprove' domain (self-dogfooding loop verb).
+    expect(CANONICAL_DOMAINS.length).toBe(24);
   });
 
   it('CANONICAL_DOMAINS contains the four sentinel newly-promoted domains', () => {

package/src/__tests__/sealed-credential.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Type + purity tests for the E10 sealed credential handle (T11752).
+ *
+ * Pins the {@link SealedCredential} / {@link DecryptedToken} contract so that:
+ *   - `SealedCredential` is exactly `{ provider, account, fetch }` with
+ *     `fetch: () => Promise<DecryptedToken>` (AC1).
+ *   - `ResolvedLLM` carries a sealed-credential-typed field (AC2).
+ *   - `DecryptedToken` is a *branded* string — a plain `string` is NOT
+ *     assignable to it, so the secret cannot be silently fabricated and a
+ *     `DecryptedToken` cannot leak into an arbitrary `string` sink without an
+ *     explicit `.value` read (the "never serialized" invariant, AC2).
+ *   - The module is types-only (no runtime export), satisfying contracts
+ *     purity (Gate 10 · AC3).
+ *
+ * @task T11752
+ * @epic T11746
+ */
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ProviderId } from '../llm/provider-id.js';
+import type { DecryptedToken, SealedCredential } from '../llm/sealed-credential.js';
+import type { ResolvedLLM } from '../operations/llm.js';
+
+describe('SealedCredential shape (AC1)', () => {
+  it('is exactly { provider, account, tokenPreview, fetch } — pins the field set', () => {
+    expectTypeOf<keyof SealedCredential>().toEqualTypeOf<
+      'provider' | 'account' | 'tokenPreview' | 'fetch'
+    >();
+  });
+
+  it('provider is a ProviderId', () => {
+    expectTypeOf<SealedCredential['provider']>().toEqualTypeOf<ProviderId>();
+  });
+
+  it('account is a plain (loggable) string', () => {
+    expectTypeOf<SealedCredential['account']>().toEqualTypeOf<string>();
+  });
+
+  it('tokenPreview is a plain (loggable, non-secret) string (T11754)', () => {
+    expectTypeOf<SealedCredential['tokenPreview']>().toEqualTypeOf<string>();
+  });
+
+  it('fetch resolves to a DecryptedToken (never a bare string)', () => {
+    expectTypeOf<SealedCredential['fetch']>().toEqualTypeOf<() => Promise<DecryptedToken>>();
+    expectTypeOf<ReturnType<SealedCredential['fetch']>>().resolves.toEqualTypeOf<DecryptedToken>();
+  });
+
+  it('all fields are readonly (a handle cannot be mutated in place)', () => {
+    // Removing `readonly` from any field would make this fail to compile.
+    expectTypeOf<SealedCredential>().toEqualTypeOf<{
+      readonly provider: ProviderId;
+      readonly account: string;
+      readonly tokenPreview: string;
+      readonly fetch: () => Promise<DecryptedToken>;
+    }>();
+  });
+});
+
+describe('DecryptedToken branding (AC2 — never serialized / never fabricated)', () => {
+  it('is NOT assignable from a plain string (nominal brand)', () => {
+    // A plain string lacks the phantom `__decryptedToken` brand, so it cannot
+    // be passed where a DecryptedToken is required.
+    expectTypeOf<string>().not.toMatchTypeOf<DecryptedToken>();
+  });
+
+  it('is NOT a plain string sink (must read .value explicitly to serialize)', () => {
+    expectTypeOf<DecryptedToken>().not.toEqualTypeOf<string>();
+  });
+
+  it('exposes a readonly plaintext .value of type string', () => {
+    expectTypeOf<DecryptedToken['value']>().toEqualTypeOf<string>();
+  });
+
+  it('carries the phantom brand marker (compile-time only)', () => {
+    expectTypeOf<DecryptedToken['__decryptedToken']>().toEqualTypeOf<'DecryptedToken'>();
+  });
+});
+
+describe('ResolvedLLM.sealedCredential (AC2 · T11753)', () => {
+  it('is the required (non-optional) canonical credential surface', () => {
+    // T11753 promotes the field from optional to required: the resolver ALWAYS
+    // populates it (a handle when a credential resolved, `null` otherwise).
+    expectTypeOf<ResolvedLLM['sealedCredential']>().toEqualTypeOf<SealedCredential | null>();
+  });
+
+  it('the inline credential metadata carries NO plaintext apiKey (T11753)', () => {
+    // The secret-bearing `apiKey` field is structurally removed from the inline
+    // credential — the plaintext crosses ONLY through `sealedCredential.fetch()`.
+    type Cred = NonNullable<ResolvedLLM['credential']>;
+    expectTypeOf<Cred>().not.toHaveProperty('apiKey');
+  });
+});
+
+describe('contracts purity (AC3) — sealed-credential is types-only', () => {
+  it('the module exposes no runtime exports (no decrypt logic in contracts)', async () => {
+    const mod = await import('../llm/sealed-credential.js');
+    // A pure type module compiles to an empty ESM namespace at runtime.
+    expect(Object.keys(mod)).toHaveLength(0);
+  });
+});

package/src/__tests__/skill-executor-contract.test.ts

@@ -43,6 +43,9 @@ const fakeTools: GuardedToolSurface = {
   async executeShell(_input): Promise<ExecuteShellResult> {
     return { stdout: '', stderr: '', code: 0 };
   },
+  async executePty(_input) {
+    return { stdout: '', stderr: '', code: 0, mode: 'spawn', ptyFellBack: false };
+  },
   async runGit(_input): Promise<ExecuteShellResult> {
     return { stdout: '', stderr: '', code: 0 };
   },

package/src/acceptance-gate.ts

@@ -325,9 +325,8 @@ export type GateResultDetails =
  * Persisted to `lifecycle_gate_results` and summarised in
  * `task.verification.gateResults`.
  *
- * NOTE: Named `AcceptanceGateResult` (not `GateResult`) to avoid collision
- * with the existing {@link GateResult} from `./warp-chain.js` which describes
- * WarpChain LOOM-gate evaluation outcomes.
+ * NOTE: Named `AcceptanceGateResult` (not `GateResult`) for historical
+ * clarity — it describes acceptance-criterion gate outcomes specifically.
  */
 export interface AcceptanceGateResult {
   /** Zero-based index in the task's acceptance array. */

package/src/boundary.ts

@@ -266,25 +266,6 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     rationale:
       'napi binding shim for cant-core + cant-runtime. Loaded via packages/cant/src/native-loader.ts and packages/core/src/system/dependencies.ts. Internal-only — shipped via per-platform packages/cant-napi-* npm packages, not crates.io. cant-router bindings removed (E8 T11432).',
   },
-  {
-    module: 'cant-router',
-    intent: 'cpu-bound',
-    rustCore: 'crates/cant-router',
-    canonicalHome: 'cleocode',
-    perfBudget: {
-      latency_p50_ms: 5,
-      latency_p99_ms: 50,
-    },
-    safetyBudget: {
-      panic_unwind: 'forbidden',
-      root_escape: 'forbidden',
-    },
-    amendments: [],
-    rationale:
-      'Cant Router (984 LOC) — RETIRED from cant-napi dep-set (E8 T11432: zero live TS consumers). ' +
-      'Preserved in the workspace for reference; not linked into the published napi binary. ' +
-      'publish=false. Relocation/deletion tracked in T11432.',
-  },
   {
     module: 'cant-runtime',
     intent: 'cpu-bound',
@@ -368,7 +349,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'Internal Rust test harness (241 LOC) over lafs-core/cleo-conduit-core/cant-core/cant-router/signaldock-core. publish=false intentional — test code never ships.',
+      'Internal Rust test harness over lafs-core/cleo-conduit-core/cant-core. publish=false intentional — test code never ships.',
   },
   {
     module: 'lafs-core',

package/src/config.ts

@@ -475,6 +475,29 @@ export interface LlmProfileTuning {
   temperature?: number;
 }
 
+/**
+ * Capability lane a named profile occupies — the hermes "global-base +
+ * granular-override" tiering model (E9 · T11745 · T11748).
+ *
+ * A profile's `tier` is a coarse capability hint a runner can use to pick the
+ * right lane for a turn independently of the role/system axis:
+ *
+ * | Tier         | Meaning                                                          |
+ * |--------------|------------------------------------------------------------------|
+ * | `prime`      | The flagship reasoning lane — orchestration / hard turns.         |
+ * | `aux`        | The auxiliary lane — cheap background subsystems (the hermes      |
+ * |              | `_AUX_TASKS` default model bucket; see {@link LlmProfileConfig.defaultAuxModel}). |
+ * | `background` | The lowest lane — fire-and-forget background work (titles, etc.). |
+ *
+ * Advisory metadata only: it does NOT alter the provider/model resolution
+ * chain in {@link LlmConfig} — it lets callers and diagnostics reason about
+ * which lane a profile belongs to without re-deriving it from the model id.
+ *
+ * @task T11748
+ * @epic T11745
+ */
+export type LlmProfileTier = 'prime' | 'aux' | 'background';
+
 /**
  * A named, reusable LLM profile.
  *
@@ -503,6 +526,67 @@ export interface LlmProfileConfig {
   credentialLabel?: string;
   /** Optional tuning parameters (max tokens, temperature). */
   params?: LlmProfileTuning;
+  /**
+   * Optional capability lane this profile occupies (see {@link LlmProfileTier}).
+   *
+   * Advisory metadata only — does NOT participate in provider/model resolution.
+   * Lets callers/diagnostics reason about a profile's lane (prime/aux/background)
+   * without re-deriving it from the model id. The hermes tiering model.
+   *
+   * @task T11748
+   */
+  tier?: LlmProfileTier;
+  /**
+   * Optional default auxiliary model for this profile — the hermes
+   * `auxiliary.defaultModel` analog (E9 · T11748).
+   *
+   * When this profile is a `prime`/global-base binding, `defaultAuxModel` names
+   * the cheaper model an aux-tier subsystem should use instead of {@link model}
+   * when it has no more-specific binding. Advisory metadata; consumers that want
+   * an aux-tier model read this rather than re-selecting a profile.
+   *
+   * @task T11748
+   */
+  defaultAuxModel?: string;
+}
+
+/**
+ * A per-system LLM binding — the granular override half of the hermes
+ * "global-base + granular-override" model (E9 · T11745 · T11748).
+ *
+ * A {@link LlmConfig.systems} entry pins the provider/model (or a named
+ * {@link LlmProfileConfig}) for ONE encoded system-of-use key (e.g.
+ * `'sentient'`, `'tool:web-search'`, `'skill:ct-cleo'`). It is consulted in the
+ * resolution chain AFTER an explicit role/argument override but BEFORE the
+ * global {@link LlmConfig.defaultProfile} — giving each subsystem a targeted
+ * override without touching the global base.
+ *
+ * Either `profile` (a key of {@link LlmConfig.profiles}) OR an inline
+ * `provider` + `model` tuple supplies the binding; `profile` wins when both are
+ * present. An entry that supplies neither a resolvable `profile` nor a complete
+ * `provider`+`model` tuple is structurally incomplete and is skipped (resolution
+ * falls through to the next tier) — never an error.
+ *
+ * @task T11748
+ * @epic T11745
+ */
+export interface SystemBinding {
+  /**
+   * Optional reference to a named profile in {@link LlmConfig.profiles}. When
+   * set and resolvable, the named profile's provider/model/credentialLabel win
+   * over this entry's inline `provider`/`model`.
+   */
+  profile?: string;
+  /** Inline LLM provider transport for this system (used when `profile` absent). */
+  provider?: LlmProviderTransport;
+  /** Inline full model identifier for this system (used when `profile` absent). */
+  model?: string;
+  /**
+   * Optional credential label pinning this system to a specific credential pool
+   * entry. When omitted, the standard priority-based credential resolution
+   * applies (or the resolved profile's `credentialLabel`).
+   */
+  credentialLabel?: string;
 }
 
 /**
@@ -559,6 +643,26 @@ export interface LlmConfig {
    * @task T11617
    */
   defaultProfile?: string;
+  /**
+   * Per-system-of-use LLM overrides — the granular-override half of the hermes
+   * "global-base + granular-override" model (E9 · T11745 · T11748).
+   *
+   * Keyed by an encoded system-of-use key: a flat role-mapped label
+   * (`'sentient'`, `'memory'`, …) or an open-axis key
+   * (`'tool:<name>'` / `'skill:<name>'` / `'cantbook:<node>'` /
+   * `'spawn-unit:<id>'`). Each value is a {@link SystemBinding}.
+   *
+   * Resolution priority for a system-of-use call:
+   *   explicit-arg (role override) → `systems[key]` → `defaultProfile` →
+   *   implicit fallback.
+   *
+   * `systems[key]` is consulted AFTER any explicit role/argument override but
+   * BEFORE the global {@link defaultProfile}, so a subsystem can be pointed at a
+   * targeted model without disturbing the global base.
+   *
+   * @task T11748
+   */
+  systems?: Record<string, SystemBinding>;
 }
 
 /** SignalDock transport mode. */

package/src/data-accessor.ts

@@ -468,9 +468,30 @@ export interface DataAccessor {
 
   // ---- Fine-grained session operations ----
 
-  /** Get the currently active session (status='active', most recent). */
+  /**
+   * Get the currently active session (status='active', most recent).
+   *
+   * SCAN-meaning: answers "is there any active session?" — NOT "who am I".
+   * Identity-meaning callers MUST use {@link DataAccessor.resolveCurrentSession}
+   * (T11640), which resolves the caller's OWN session via the
+   * connection-handle → `CLEO_SESSION_ID` → most-recent-active precedence.
+   */
   getActiveSession(): Promise<Session | null>;
 
+  /**
+   * Resolve the CALLER's current session (T11640 · Epic T11638).
+   *
+   * Identity-meaning resolution for accessor-based consumers, mirroring the
+   * standalone `resolveCurrentSession` in `@cleocode/core`. Precedence:
+   *   1. daemon connection handle (the connection bound at accept-time),
+   *   2. env-named session (`CLEO_SESSION_ID`),
+   *   3. most-recent-active row (legacy single-process fallback).
+   *
+   * Use this — NOT {@link DataAccessor.getActiveSession} — anywhere the meaning
+   * is "the session of whoever issued THIS request".
+   */
+  resolveCurrentSession(): Promise<Session | null>;
+
   /** Upsert a single session (targeted write). */
   upsertSingleSession(session: Session): Promise<void>;
 

package/src/dispatch/identity.ts

@@ -99,6 +99,11 @@ export const CANONICAL_DOMAINS = [
   // T11373: 'cleo attention add|show|list' (alias 'jot') — Tier-2 scope-keyed
   // working-memory buffer (Epic T11288 · Saga T11283).
   'attention',
+  // T11889 (T11889-D): 'cleo selfimprove run' — the self-dogfooding loop verb.
+  // Boots ONE sandbox → replays a canned scenario → diffs vs golden → on a
+  // regression emits ONE leased `selfimprove_dhq` row + ONE DRAFT PR. Default
+  // OFF (requires --execute); the engine lives in CORE (P5 self-improvement spec).
+  'selfimprove',
 ] as const;
 
 /**

package/src/dispatch/operations-registry.ts

@@ -1462,37 +1462,6 @@ export const OPERATIONS: OperationDef[] = [
     requiredParams: [],
     params: [],
   },
-  // T5405: WarpChain pipeline operations
-  {
-    gateway: 'query',
-    domain: 'pipeline',
-    operation: 'chain.show',
-    description: 'pipeline.chain.show (query) — get chain definition by ID',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: ['chainId'],
-    params: [
-      {
-        name: 'chainId',
-        type: 'string',
-        required: true,
-        description: 'chainId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'query',
-    domain: 'pipeline',
-    operation: 'chain.list',
-    description: 'pipeline.chain.list (query) — list all chain definitions',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: [],
-    params: [],
-  },
   {
     gateway: 'query',
     domain: 'check',
@@ -1690,26 +1659,6 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
-  // T5405: WarpChain validation query
-  {
-    gateway: 'query',
-    domain: 'check',
-    operation: 'chain.validate',
-    description: 'check.chain.validate (query) — validate a WarpChain definition',
-    tier: 2,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: ['chain'],
-    params: [
-      {
-        name: 'chain',
-        type: 'string',
-        required: true,
-        description: 'chain parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
   // T646: Canon drift detection — CI gate
   {
     gateway: 'query',
@@ -4248,77 +4197,6 @@ export const OPERATIONS: OperationDef[] = [
       { name: 'force', type: 'boolean', required: false, description: 'Required safety flag' },
     ],
   },
-  // T5405: WarpChain pipeline mutate operations
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.add',
-    description: 'pipeline.chain.add (mutate) — store a validated chain definition',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['chain'],
-    params: [
-      {
-        name: 'chain',
-        type: 'string',
-        required: true,
-        description: 'chain parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.instantiate',
-    description: 'pipeline.chain.instantiate (mutate) — create chain instance for epic',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['chainId', 'epicId'],
-    params: [
-      {
-        name: 'chainId',
-        type: 'string',
-        required: true,
-        description: 'chainId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'epicId',
-        type: 'string',
-        required: true,
-        description: 'epicId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'pipeline',
-    operation: 'chain.advance',
-    description: 'pipeline.chain.advance (mutate) — advance instance to next stage',
-    tier: 2,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['instanceId', 'nextStage'],
-    params: [
-      {
-        name: 'instanceId',
-        type: 'string',
-        required: true,
-        description: 'instanceId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'nextStage',
-        type: 'string',
-        required: true,
-        description: 'nextStage parameter',
-      },
-    ] satisfies ParamDef[],
-  },
   {
     gateway: 'mutate',
     domain: 'check',
@@ -6603,54 +6481,6 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
-  // orchestrate — tessera template operations (T5411)
-  // tessera.show removed — merged into tessera.list via optional id param (T5615)
-  {
-    gateway: 'query',
-    domain: 'orchestrate',
-    operation: 'tessera.list',
-    description:
-      'orchestrate.tessera.list (query) — list Tessera templates; absorbs tessera.show via optional id param',
-    tier: 1,
-    idempotent: true,
-    sessionRequired: false,
-    requiredParams: [],
-    params: [
-      {
-        name: 'id',
-        type: 'string',
-        required: false,
-        description: 'Optional template ID for single-item lookup (replaces tessera.show)',
-      },
-    ],
-  },
-  {
-    gateway: 'mutate',
-    domain: 'orchestrate',
-    operation: 'tessera.instantiate',
-    description:
-      'orchestrate.tessera.instantiate (mutate) — instantiate a Tessera template into a chain instance',
-    tier: 1,
-    idempotent: false,
-    sessionRequired: false,
-    requiredParams: ['templateId', 'epicId'],
-    params: [
-      {
-        name: 'templateId',
-        type: 'string',
-        required: true,
-        description: 'templateId parameter',
-        cli: { positional: true },
-      },
-      {
-        name: 'epicId',
-        type: 'string',
-        required: true,
-        description: 'epicId parameter',
-        cli: { positional: true },
-      },
-    ] satisfies ParamDef[],
-  },
   // orchestrate — Wave 7a dispatch ops (T408, T409, T410, T415)
   {
     gateway: 'query',
@@ -8956,4 +8786,55 @@ export const OPERATIONS: OperationDef[] = [
       },
     ] satisfies ParamDef[],
   },
+
+  // ── selfimprove mutate: run (T11889 / T11889-D — the self-dogfooding loop) ──
+  // Boots ONE sandbox → replays the named canned scenario → diffs result
+  // envelopes vs the golden → on a regression emits ONE leased `selfimprove_dhq`
+  // row and opens ONE DRAFT PR. The walking skeleton's default scenario is
+  // query-only so the in-process replay never mutates. DEFAULT OFF: without
+  // `execute` the loop runs DRY-RUN (replay + diff + report; NO DB write, NO PR).
+  // The CORE engine (`runSelfImprove`) owns boot/replay/diff/persist/egress +
+  // the budget + circuit-breaker; the dispatch handler is a thin delegate that
+  // supplies the in-process `ReplayDispatch` port (Gate-6). `sessionRequired`
+  // links each run to its origin session for provenance.
+  {
+    gateway: 'mutate',
+    domain: 'selfimprove',
+    operation: 'run',
+    description:
+      'selfimprove.run (mutate) — boot ONE sandbox, replay a canned dogfood scenario, diff vs golden; on regression emit ONE leased selfimprove_dhq row + ONE DRAFT PR. Default OFF — requires --execute (else DRY-RUN). Budget-capped + circuit-broken (T11889 / T11889-D).',
+    tier: 2,
+    idempotent: false,
+    sessionRequired: true,
+    requiredParams: ['scenario'],
+    params: [
+      {
+        name: 'scenario',
+        type: 'string',
+        required: true,
+        description: 'Canned dogfood scenario name to replay (e.g. dhq-replay-find)',
+      },
+      {
+        name: 'execute',
+        type: 'boolean',
+        required: false,
+        description:
+          'Permit mutation (leased DHQ UPSERT) + egress (draft PR). DEFAULT false ⇒ DRY-RUN (replay + diff + report only — no DB write, no PR).',
+      },
+      {
+        name: 'dryRun',
+        type: 'boolean',
+        required: false,
+        description:
+          'Force DRY-RUN explicitly (no DB write, no PR). Equivalent to omitting --execute; the loop is default-OFF.',
+      },
+      {
+        name: 'backend',
+        type: 'string',
+        required: false,
+        description:
+          "Confinement backend preference: 'gondolin' (micro-VM; degrades to the in-process guarded env when VM infra is absent — the CI path) | 'guarded'. Default: gondolin.",
+      },
+    ] satisfies ParamDef[],
+  },
 ];