@cleocode/contracts 2026.9.20 → 2026.9.22

package/src/__tests__/decide.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Tests for the typed-decision contracts (T12489).
+ *
+ * @task T12489
+ */
+
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { z } from 'zod';
+import {
+  DECISION_REQUEST_LIMITS,
+  type DecisionAnswer,
+  type DecisionOutcome,
+  type DecisionQuestion,
+  decisionAnswerSchema,
+  decisionOutcomeSchema,
+  decisionProviderConfigSchema,
+  decisionQuestionSchema,
+  decisionRequestSchema,
+} from '../decide.js';
+
+const noul = { type: 'noul', criteria: 'The change is safe to merge' } as const;
+
+describe('decisionRequestSchema', () => {
+  it('accepts a request with each question shape and structured state', () => {
+    const result = decisionRequestSchema.safeParse({
+      model: 'default',
+      state: { diff: ['a', 'b'], files: 2 },
+      questions: {
+        safe: { ...noul, instructions: { strict: true } },
+        area: { type: 'choice', criteria: { api: 'Touches the API', ui: 'Touches the UI' } },
+        risk: { type: 'score', criteria: ['low', 'medium', 'high'] },
+      },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('enforces 1-32 questions', () => {
+    expect(decisionRequestSchema.safeParse({ state: 's', questions: {} }).success).toBe(false);
+    const questions = (n: number) =>
+      Object.fromEntries(Array.from({ length: n }, (_, i) => [`q${i}`, noul]));
+    expect(
+      decisionRequestSchema.safeParse({
+        state: 's',
+        questions: questions(DECISION_REQUEST_LIMITS.maxQuestions),
+      }).success,
+    ).toBe(true);
+    expect(
+      decisionRequestSchema.safeParse({
+        state: 's',
+        questions: questions(DECISION_REQUEST_LIMITS.maxQuestions + 1),
+      }).success,
+    ).toBe(false);
+  });
+
+  it('enforces the state size limit for string and structured state', () => {
+    const max = DECISION_REQUEST_LIMITS.maxStateChars;
+    const q = { q: noul };
+    expect(decisionRequestSchema.safeParse({ state: 'x'.repeat(max), questions: q }).success).toBe(
+      true,
+    );
+    expect(
+      decisionRequestSchema.safeParse({ state: 'x'.repeat(max + 1), questions: q }).success,
+    ).toBe(false);
+    expect(
+      decisionRequestSchema.safeParse({ state: ['x'.repeat(max)], questions: q }).success,
+    ).toBe(false);
+  });
+});
+
+describe('decisionQuestionSchema', () => {
+  it('requires at least two choice options', () => {
+    expect(decisionQuestionSchema.safeParse({ type: 'choice', criteria: { a: 'A' } }).success).toBe(
+      false,
+    );
+    expect(
+      decisionQuestionSchema.safeParse({ type: 'choice', criteria: { a: 'A', b: 'B' } }).success,
+    ).toBe(true);
+  });
+
+  it('requires 2-10 score levels', () => {
+    const levels = (n: number) => Array.from({ length: n }, (_, i) => `level ${i}`);
+    expect(decisionQuestionSchema.safeParse({ type: 'score', criteria: levels(1) }).success).toBe(
+      false,
+    );
+    expect(decisionQuestionSchema.safeParse({ type: 'score', criteria: levels(2) }).success).toBe(
+      true,
+    );
+    expect(decisionQuestionSchema.safeParse({ type: 'score', criteria: levels(10) }).success).toBe(
+      true,
+    );
+    expect(decisionQuestionSchema.safeParse({ type: 'score', criteria: levels(11) }).success).toBe(
+      false,
+    );
+  });
+});
+
+describe('answer, outcome and provider config schemas', () => {
+  it('rejects probabilities outside [0, 1]', () => {
+    expect(
+      decisionAnswerSchema.safeParse({
+        type: 'noul',
+        value: true,
+        probability: 1.2,
+        confidence: 0.9,
+      }).success,
+    ).toBe(false);
+  });
+
+  it('accepts a cached outcome', () => {
+    const outcome: DecisionOutcome = {
+      answers: {
+        safe: { type: 'noul', value: true, probability: 0.8, confidence: 0.7 },
+        area: {
+          type: 'choice',
+          value: 'api',
+          probabilities: { api: 0.9, ui: 0.1 },
+          confidence: 0.6,
+        },
+        risk: { type: 'score', value: 0, probabilities: [0.7, 0.2, 0.1], confidence: 0.5 },
+      },
+      source: 'cache',
+      latencyMs: 3,
+    };
+    expect(decisionOutcomeSchema.parse(outcome)).toEqual(outcome);
+  });
+
+  it('requires an absolute baseUrl', () => {
+    expect(
+      decisionProviderConfigSchema.safeParse({ baseUrl: 'https://example.test' }).success,
+    ).toBe(true);
+    expect(decisionProviderConfigSchema.safeParse({ baseUrl: 'not a url' }).success).toBe(false);
+  });
+
+  it('schema outputs are assignable to the domain types', () => {
+    expectTypeOf<z.output<typeof decisionQuestionSchema>>().toExtend<DecisionQuestion>();
+    expectTypeOf<z.output<typeof decisionAnswerSchema>>().toExtend<DecisionAnswer>();
+    expectTypeOf<z.output<typeof decisionOutcomeSchema>>().toExtend<DecisionOutcome>();
+  });
+});

package/src/__tests__/evidence-atom-schema.test.ts

@@ -31,7 +31,7 @@ describe('EvidenceAtomSchema (T10337)', () => {
   it('EVIDENCE_ATOM_KINDS covers every discriminated union member (T12030)', () => {
     // Verify the shared constant is in sync with the zod discriminated union.
     // The discriminated union keys are 'commit','files','test-run','tool','url',
-    // 'note','decision','pr','loc-drop','callsite-coverage','satisfies'.
+    // 'note','decision','pr','ci','loc-drop','callsite-coverage','satisfies'.
     const expected = [
       'commit',
       'files',
@@ -41,6 +41,7 @@ describe('EvidenceAtomSchema (T10337)', () => {
       'note',
       'decision',
       'pr',
+      'ci',
       'loc-drop',
       'callsite-coverage',
       'satisfies',
@@ -498,6 +499,28 @@ describe('parseEvidenceString (T10337)', () => {
 
 // ─── GATE_EVIDENCE_REQUIREMENTS — gate-to-atom mapping ─────────────────────
 
+describe('pr:/ci: component references (T12671)', () => {
+  it('pr:<component>@<integration> names the integration PR and its component', () => {
+    expect(parseEvidenceString('pr:42@41')).toEqual([
+      { kind: 'pr', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('ci:42@41')).toEqual([
+      { kind: 'ci', prNumber: 41, componentPrNumber: 42 },
+    ]);
+    expect(parseEvidenceString('pr:41')).toEqual([{ kind: 'pr', prNumber: 41 }]);
+  });
+
+  it.each(['pr:42@42', 'pr:42@', 'pr:@41', 'ci:0@41', 'pr:42@4x'])('rejects %s', (raw) => {
+    expect(() => parseEvidenceString(raw)).toThrow(EvidenceParseError);
+  });
+
+  it('the schema accepts the component field', () => {
+    expect(
+      EvidenceAtomSchema.safeParse({ kind: 'ci', prNumber: 41, componentPrNumber: 42 }).success,
+    ).toBe(true);
+  });
+});
+
 describe('GATE_EVIDENCE_REQUIREMENTS (T10337)', () => {
   it('covers every VerificationGate', () => {
     const expected: VerificationGate[] = [

package/src/__tests__/memory-wire-shapes.test.ts

@@ -205,6 +205,7 @@ type _ObserveBrainParamsShape = {
   attachmentRefs?: string[];
   origin?: string | null;
   provenanceChain?: string[] | null;
+  askTypeDecision?: boolean;
   _skipGate?: boolean;
   _skipQueue?: boolean;
 };
@@ -219,6 +220,8 @@ type _ObserveBrainResultShape = {
   id: string;
   type: string;
   createdAt: string;
+  typeSource?: 'caller' | 'keyword' | 'system-one';
+  typeConfidence?: number;
 };
 
 type _AssertObserveResultPinned = AssertEquals1<

package/src/acceptance-gate-schema.ts

@@ -443,6 +443,25 @@ const acceptanceGateBindingSchema: z.ZodType<AcceptanceGateBinding> = z
             });
         }),
     ),
+    tree: z
+      .object({
+        headSha: z.string().regex(/^[0-9a-f]{40}$/),
+        clean: z.boolean(),
+        cwd: z
+          .string()
+          .min(1)
+          .refine(
+            (v) => !/^(?:\/|[A-Za-z]:[\\/]|\\\\)/.test(v) && !v.split(/[\\/]/).includes('..'),
+            'Tree-relative cwd must be relative and stay inside the tree',
+          ),
+        inputsHash: z.string().regex(/^[a-f0-9]{64}$/),
+        baseSha: z
+          .string()
+          .regex(/^[0-9a-f]{40}$/)
+          .optional(),
+      })
+      .strict()
+      .optional(),
   })
   .strict()
   .superRefine((binding, context) => {
@@ -490,8 +509,18 @@ export const acceptanceGateResultSchema = z
     /** ISO 8601 timestamp. */
     checkedAt: z.string().datetime(),
     checkedBy: z.string().min(1),
+    /** T12621: `executed` in this run, or an authenticated pass reused from the cache. */
+    source: z.enum(['executed', 'cache']).optional(),
+    /** T12621: creation time of the reused cache entry. */
+    cachedAt: z.string().datetime().optional(),
   })
   .superRefine((result, context) => {
+    if ((result.source === 'cache') !== (result.cachedAt !== undefined))
+      context.addIssue({
+        code: 'custom',
+        path: ['cachedAt'],
+        message: 'A cached result carries its cache time, and only a cached result does',
+      });
     const binding = result.binding;
     if (binding) {
       if (binding.identity.actor !== result.checkedBy)

package/src/acceptance-gate.ts

@@ -28,8 +28,8 @@ import type {
 
 /**
  * Captured options for evaluating acceptance gates without renewing operation authority.
- * @remarks An absent execution context receives a two-second shared foreground budget.
- * Per-gate timeouts can tighten it; long work requires explicit runtime admission.
+ * @remarks An absent execution context is admitted for every gate's tool deadline plus
+ * the two-second bookkeeping budget (T12516); per-gate timeouts bound each gate.
  * @example
  * ```typescript
  * const options: AcceptanceGateRunOptions = { projectRoot: '/project', execution };
@@ -49,6 +49,23 @@ export interface AcceptanceGateRunOptions
   maxOutputBytes?: number;
   /** Existing manager context, separate from the child environment. */
   systemdControl?: SystemdControlContext;
+  /**
+   * Typed-gate result cache policy (T12621). Keyed by gate definition hash, git
+   * HEAD, dirty-tree fingerprint and cwd; only passes are stored.
+   * - `off`: never read or write the cache.
+   * - `refresh`: always execute, then store a pass (`cleo verify --run`).
+   * - `use`: serve a fresh cached pass, otherwise execute and store a pass.
+   * - `only`: serve a fresh cached pass; a cacheable gate without one is an
+   *   `error` result and is never executed (`cleo verify --no-run`).
+   *
+   * @defaultValue 'off'
+   */
+  cache?: 'off' | 'refresh' | 'use' | 'only';
+  /**
+   * Digest of the single gate's captured invocation and input artifacts; part of
+   * its cache key. Required, with a one-gate batch, whenever `cache` is not `off`.
+   */
+  cacheInputsHash?: string;
 }
 
 // ─── Base ────────────────────────────────────────────────────────────────────
@@ -80,7 +97,10 @@ export interface GateBase {
   /**
    * Gate timeout in milliseconds.
    *
-   * @defaultValue 60_000 (further bounded by the shared operation deadline)
+   * @defaultValue The ADR-061 tool deadline for the gate kind: `CLEO_GATE_TIMEOUT_MS`,
+   * else `CLEO_TOOL_TIMEOUT_<KIND>`, else 1_800_000 for `test` and 300_000 otherwise
+   * (T12516). It bounds the gate's own execution; the two-second shared budget
+   * covers only the surrounding bookkeeping, never a gate (T12621).
    */
   timeoutMs?: number;
 }
@@ -434,6 +454,37 @@ export interface AcceptanceGateBinding {
   invocation?: AcceptanceGateInvocation;
   /** Explicit bounded input inventory, including untracked harness/task files. */
   artifacts: AcceptanceGateArtifact[];
+  /**
+   * Content binding of the tree the gate ran in (T12625). Lets a result
+   * verified in a worker's worktree be revalidated from another checkout of
+   * the same project — the orchestrator completing from main after merge —
+   * without re-entering the (often auto-cleaned) worktree. Absent on results
+   * recorded before T12625, which keep exact path-bound revalidation.
+   */
+  tree?: AcceptanceGateTreeBinding;
+}
+
+/**
+ * Tree-independent binding of a typed gate's inputs (T12625).
+ * @remarks Revalidation from another tree of the same project accepts only when
+ * the verified tree was clean, `headSha` is an ancestor of the completing HEAD,
+ * and `inputsHash` recomputes identically there.
+ */
+export interface AcceptanceGateTreeBinding {
+  /** HEAD commit of the tree the gate ran in. */
+  headSha: string;
+  /** True when that tree had no uncommitted tracked changes. */
+  clean: boolean;
+  /** Gate working directory, relative to the tree root (`.` for the root). */
+  cwd: string;
+  /** SHA-256 over command, args, relative cwd, environment hash and repo-relative input bytes. */
+  inputsHash: string;
+  /**
+   * Fork point of the verified commit from origin's default branch at
+   * verification time. `baseSha..headSha` is the change the result attests;
+   * every path it touched must be unchanged in the completing tree.
+   */
+  baseSha?: string;
 }
 
 /**
@@ -504,6 +555,14 @@ export interface AcceptanceGateResult {
   checkedAt: string;
   /** Agent identifier or `"human"` that ran or attested the gate. */
   checkedBy: string;
+  /**
+   * Where the verdict came from (T12621): `executed` in this run, or `cache` —
+   * an authenticated pass reused from the ADR-061 evidence cache. Absent on
+   * results recorded before T12621.
+   */
+  source?: 'executed' | 'cache';
+  /** When the reused cache entry was created (the original execution); set iff `source` is `cache`. */
+  cachedAt?: string;
 }
 
 /** Canonical typed-verification audit details stored with results in the task transaction. */
@@ -516,4 +575,10 @@ export interface AcceptanceGateVerificationReceipt {
   operation: 'check.gate.verify';
   /** Overall generic-plus-typed verification outcome at this observation. */
   passed: boolean;
+  /**
+   * Results reused from the evidence cache instead of executed (T12621), by
+   * acceptance index, with each cache entry's creation time. Omitted when every
+   * result was executed, so receipts recorded before T12621 stay byte-identical.
+   */
+  cached?: Array<{ index: number; cachedAt: string }>;
 }

package/src/backup-manifest.ts

@@ -254,8 +254,19 @@ export interface BackupObservationInspection {
     atimeNs: string;
     /** Observed access time at the final identity/content-metadata recheck. */
     atimeAfterNs: string;
-    /** Whether access time changed; this does not identify the responsible reader. */
-    atimeChanged: boolean;
+    /**
+     * Whether access time changed; this does not identify the responsible reader.
+     * `null` when {@link atimeIsolation} is `'unavailable'`: the inspection's own
+     * read may have advanced atime, so a change is not evidence of another reader.
+     */
+    atimeChanged: boolean | null;
+    /**
+     * Whether the inspection's own read was kept from updating access time.
+     * `'noatime'`: the source was opened with O_NOATIME (Linux).
+     * `'unavailable'`: the platform has no O_NOATIME (macOS), so atime may
+     * reflect this inspection.
+     */
+    atimeIsolation: 'noatime' | 'unavailable';
   };
   /** Actual SQLite schema marker; not an inferred product/schema version. */
   userVersion: number;

package/src/branch-lock.ts

@@ -320,6 +320,13 @@ export const BRANCH_LOCK_ERROR_CODES = {
    * reset the branch automatically.
    */
   E_DIRTY_BRANCH: 'E_DIRTY_BRANCH',
+  /**
+   * T12506: the per-task worktree lock is held by a live holder (pid alive with
+   * the recorded start time, heartbeat within the TTL). A second spawn would
+   * otherwise force-remove the holder's live worktree. Error details name the
+   * holder. Exit code `ExitCode.WORKTREE_LOCKED` (25).
+   */
+  E_WORKTREE_LOCKED: 'E_WORKTREE_LOCKED',
 } as const;
 
 /** Union of all branch-lock error code strings. */
@@ -501,6 +508,10 @@ export interface IsolationResult {
    *     against symlink traversal and shell quirks).
    *  3. Exports the isolation env vars so they are visible to child processes.
    *
+   * Every path and value is POSIX single-quoted, so the snippet stays a valid
+   * shell program when the worktree path contains spaces (the macOS default
+   * `~/Library/Application Support/...`), `$`, backticks or quotes (T12520).
+   *
    * The trailing newline is included so callers can concatenate directly.
    */
   preamble: string;
@@ -512,6 +523,24 @@ export interface IsolationResult {
   boundaryContract: BoundaryContract;
 }
 
+/**
+ * POSIX single-quote one shell word: wrap it in `'...'` and rewrite each
+ * embedded `'` as `'\''`. The result is one literal word for any input — no
+ * parameter, command or glob expansion — which is what a copy-paste snippet
+ * naming a path under `Application Support` needs (T12520).
+ *
+ * Module-private on purpose: contracts is types-only for its exported surface
+ * (gate 10), and {@link provisionIsolatedShell} is the one place that renders
+ * isolation paths into shell text, so callers consume the quoted preamble
+ * rather than re-quoting.
+ *
+ * @param value - Raw path or value.
+ * @returns The single-quoted shell word.
+ */
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
 /**
  * Provision an isolated shell context for an agent worktree.
  *
@@ -561,19 +590,22 @@ export function provisionIsolatedShell(options: IsolationOptions): IsolationResu
   // does not emit a clobbering `export KEY=""` that would clear an inherited
   // value. Worktree-binding keys are always non-empty so they always export.
   const exportBlock = ISOLATION_ENV_KEYS.filter((k) => env[k] !== '')
-    .map((k) => `export ${k}="${env[k]}"`)
+    .map((k) => `export ${k}=${shellQuote(env[k])}`)
     .join('\n');
 
+  // 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);
   const preamble = [
     '## Worktree Isolation (REQUIRED — do not skip)',
     '',
     '# Step 1: Enter the worktree (exits immediately if path is missing)',
-    `cd "${worktreePath}" || exit 1`,
+    `cd ${quotedPath} || exit 1`,
     '',
     '# Step 2: Verify working directory (guards against shell/symlink quirks)',
     'case "$PWD" in',
-    `  "${worktreePath}"*) ;;`,
-    '  *) echo "ISOLATION ERROR: pwd=$PWD expected prefix=' + worktreePath + '" >&2; exit 1 ;;',
+    `  ${quotedPath}*) ;;`,
+    `  *) echo "ISOLATION ERROR: pwd=$PWD expected prefix="${quotedPath} >&2; exit 1 ;;`,
     'esac',
     '',
     '# Step 3: Export isolation env vars',