@cleocode/contracts 2026.10.8 → 2026.10.9-rc.ci.676

package/src/branch-lock.ts

@@ -193,8 +193,11 @@ export interface GitShimEnv {
   CLEO_ALLOW_BRANCH_OPS?: '1';
   /** Worktree root path — informational for shim error messages. */
   CLEO_WORKTREE_ROOT?: string;
-  /** Branch protection mode. */
-  CLEO_BRANCH_PROTECTION?: 'strict' | 'permissive' | 'off';
+  /**
+   * Branch protection mode. `unavailable`: strict was intended but the git
+   * shim could not be installed, so nothing enforces it (T13522).
+   */
+  CLEO_BRANCH_PROTECTION?: 'strict' | 'permissive' | 'off' | 'unavailable';
 }
 
 /**

package/src/dispatch/operations-registry.ts

@@ -9428,7 +9428,7 @@ export const OPERATIONS: OperationDef[] = [
         name: 'channel',
         type: 'string',
         required: false,
-        description: 'Release channel: latest | beta | alpha | rc',
+        description: 'Release channel: latest | beta | alpha | rc | canary',
       },
       {
         name: 'hotfix',
@@ -9436,6 +9436,12 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'Mark plan as release_kind=hotfix',
       },
+      {
+        name: 'hooksV1Promotion',
+        type: 'boolean',
+        required: false,
+        description: 'Require the unified-hooks pilot for this stable promotion',
+      },
       {
         name: 'dryRun',
         type: 'boolean',

package/src/index.ts

@@ -2032,6 +2032,7 @@ export type {
   WorktreeHookResult,
   WorktreeIncludePattern,
   WorktreeInfo,
+  WorktreeInstallOutcome,
   WorktreeLifecycleAction,
   WorktreeLifecycleAuditEntry,
   WorktreeListEntry,
@@ -3163,6 +3164,12 @@ export {
   type CloudConflict,
   type CloudConflictResolveResult,
   type CloudConflictsResult,
+  type CloudDeviceOverviewResult,
+  type CloudDeviceOverviewRow,
+  type CloudJournalActivityDevice,
+  type CloudJournalActivityItem,
+  type CloudJournalActivityResult,
+  type CloudJournalTableOps,
   type CloudLeaseReleaseResult,
   type CloudPushResult,
   type CloudRestoreResult,

package/src/invariants/sync-write-invariants.ts

@@ -490,7 +490,16 @@ export const SYNC_WRITE_INVARIANTS: readonly SyncWriteInvariant[] = Object.freez
   {
     id: 'identity.local-minting',
     class: 'identity-layer',
-    tables: ['tasks_tasks', 'tasks_sessions'],
+    // T13405: the counter-key re-mint after a uid collision renames these too.
+    tables: [
+      'tasks_tasks',
+      'tasks_sessions',
+      'brain_decisions',
+      'brain_sticky_notes',
+      'brain_sticky_tags',
+      'brain_page_nodes',
+      'brain_page_edges',
+    ],
     sites: [],
     inventory: ['V12', 'B07', 'B12'],
     reason:

package/src/nexus-cloud.ts

@@ -145,6 +145,10 @@ export const nexusCloudReplicaSchema = z.object({
   lastSyncAt: isoTime.nullable(),
   presence: nexusCloudPresenceSchema.nullable(),
   presenceAt: isoTime.nullable(),
+  /** When the replica was retired (cleo-nexus T123), else null. Absent from servers older than retirement. */
+  retiredAt: isoTime.nullable().optional(),
+  /** The retired replica's named successor, else null (not retired, or retired with none). */
+  successor: z.string().nullable().optional(),
 });
 
 /** `DeviceCounts` (§4.1): distinct devices holding a replica. */
@@ -631,7 +635,11 @@ export interface CloudStatusSeenTxns {
 export interface CloudStatusSyncStream {
   /** Which store. */
   readonly scope: 'project' | 'global';
-  /** Its stream (`project:<id>`, `home:<userId>`) when known locally, else `null`. */
+  /**
+   * Its stream (`project:<id>`, `home:<userId>`) when known locally: from the
+   * project link, else from the store's own genesis cut or pull position
+   * (T13370); `null` before either exists.
+   */
   readonly stream: string | null;
   /** The store file. */
   readonly dbPath: string;
@@ -645,6 +653,10 @@ export interface CloudStatusSyncStream {
   readonly oldestUnsealedAtMs: number | null;
   /** The highest sealed local sequence (`_sync_txn.local_seq`), or `null` before the first seal. */
   readonly lastSealedSeq: number | null;
+  /** The local sequence of this stream's genesis cut, or `null` before the store cut or joined it (T13370). */
+  readonly genesisCut: number | null;
+  /** The cut's genesis checkpoint is not yet confirmed stored; no segment is sent until it is (T13370). */
+  readonly genesisPending: boolean;
   /** Captures the sealer could not read and holds aside (`_sync_quarantine`), per table. */
   readonly quarantined: Readonly<Record<string, number>>;
   /** Tables marked suspect until a repair re-emits them. */

package/src/nexus-vault.ts

@@ -220,9 +220,31 @@ export interface CloudSyncPushEnableResult {
    * `enabled`: the cut was recorded and its genesis checkpoint stored; `resumed`: a cut recorded
    * by an earlier run whose checkpoint push failed was pushed now; `already`: push was already on;
    * `joined`: this store holds the stream's journal checkpoint another device cut, and now pushes its
-   * own writes and pulls the stream's after it, with no genesis of its own (T13312).
+   * own writes and pulls the stream's after it, with no genesis of its own (T13312). A store that
+   * never synced with the stream joins too, keeping its own rows (see `merged`, T13466).
    */
   status: 'enabled' | 'resumed' | 'already' | 'joined';
+  /**
+   * A merge join (T13466): stream rows adopted here, this store's own rows emitted as its first
+   * transactions, and stream rows not placed (an unresolved reference). `overwritten` lists fields of
+   * this store's own rows whose older value took the stream's newer one (T13503); `safetyBackup` is
+   * the bundle of the store as it was before the merge. Null when the reconcile is still due
+   * (`cleo cloud sync` finishes it); absent on any other status.
+   */
+  merged?: {
+    adopted: number;
+    emitted: number;
+    unresolved: number;
+    overwritten: Array<{ table: string; uid: string; column: string }>;
+    /**
+     * Fields of the stream's rows that took this store's newer value on every replica (T13507);
+     * column `*` is a whole row this store's newer edit restored over a stream delete (T13508).
+     */
+    replaced: Array<{ table: string; uid: string; column: string }>;
+    /** This store's own rows a newer stream delete removed; the safety bundle holds them (T13508). */
+    deleted: Array<{ table: string; uid: string }>;
+    safetyBackup: string;
+  } | null;
   /** The genesis cut: the highest capture seq the checkpoint carries. */
   cut: number;
   /** Transactions sealed before the cut, folded into the checkpoint, and rows given genesis row meta. */
@@ -427,6 +449,121 @@ export interface CloudActivityResult {
   warnings: CloudWarning[];
 }
 
+/** Per-table op counts of one journal transaction, by op kind. */
+export interface CloudJournalTableOps {
+  I: number;
+  U: number;
+  D: number;
+  K: number;
+}
+
+/**
+ * One transaction another device (or this one, echoed back) wrote, as this
+ * store's journal received it (`cleo cloud activity --journal`, T13369).
+ */
+export interface CloudJournalActivityItem {
+  /** The transaction id, `${replicaId}:${localSeq}`. */
+  txn: string;
+  stream: string;
+  /** The segment's stream sequence number and the transaction's index in it. */
+  seq: number;
+  txnIdx: number;
+  /** The replica (store) that wrote it. */
+  replicaId: string;
+  /** The Nexus device that signed its segment. */
+  deviceId: string;
+  /** The device's name from the account's device list; `null` offline or when unknown. */
+  deviceName: string | null;
+  /** Written by a replica this machine bound. */
+  thisDevice: boolean;
+  /** The transaction's HLC. */
+  hlc: string;
+  /** When it was written: the HLC's physical time, ISO-8601. */
+  at: string;
+  /** When this store staged it, and applied it (`null` until applied). */
+  stagedAt: string;
+  appliedAt: string | null;
+  /** Inbox status: `applied`, `void`, `conflict`, `staged`, `pending`, `held-skew`, `refused-schema`. */
+  status: string;
+  /** Why it is void, held or refused, when it is. */
+  reason: string | null;
+  /**
+   * Applied as inherited history (§1.5, T13278/T13366): its replica was
+   * retired by a server-confirmed retire at a lower stream position, so the
+   * merge recorded no conflict for it. Always `false` for an unconfirmed
+   * retire or a transaction that was not applied.
+   */
+  history: boolean;
+  /** `write`, `repair`, `retire`, … and how the writes reached the store. */
+  kind: string;
+  via: string;
+  /** The command, agent and session that wrote it, when recorded. */
+  actor: { agent?: string; session?: string; op?: string } | null;
+  /** The project the transaction is for (`null` for a global-scope txn). */
+  project: string | null;
+  /** Total ops, and op counts per table. */
+  ops: number;
+  tables: Record<string, CloudJournalTableOps>;
+}
+
+/** One device's share of the journal activity matching the filters. */
+export interface CloudJournalActivityDevice {
+  deviceId: string;
+  deviceName: string | null;
+  thisDevice: boolean;
+  /** Matching transactions, and the newest one's write time (ISO-8601). */
+  txns: number;
+  lastAt: string;
+  /** The device's last presence report from the account's device list; `null` offline or when unknown. */
+  lastSeenAt: string | null;
+}
+
+/** `cleo cloud activity --journal`: what each device changed and when, from the local journal. */
+export interface CloudJournalActivityResult {
+  scope: CloudVaultScope;
+  /** Newest first. */
+  items: CloudJournalActivityItem[];
+  /** Per device, over every matching transaction (not just this page). */
+  devices: CloudJournalActivityDevice[];
+  /** Pass as `--before` for the next older page; `null` at the end. */
+  nextBefore: string | null;
+  warnings: CloudWarning[];
+}
+
+/**
+ * One device in `cleo cloud activity --devices` (T13482): its presence, its
+ * newest journal change this store received, and its newest server event.
+ */
+export interface CloudDeviceOverviewRow {
+  deviceId: string;
+  /** From the account's device list; `null` offline or when unknown. */
+  deviceName: string | null;
+  thisDevice: boolean;
+  /** `active`, `signed-out` or `revoked`; `null` when not in the device list. */
+  state: string | null;
+  /** Presence reported within the freshness window; `null` offline or when unknown. */
+  online: boolean | null;
+  lastSeenAt: string | null;
+  /** Its journal transactions in this store, and the newest one; `null` when none. */
+  journal: {
+    txns: number;
+    lastAt: string;
+    /** Command (or txn kind), inbox status and tables of the newest transaction on the page read. */
+    last: { op: string; status: string; tables: string[] } | null;
+  } | null;
+  /** Its newest server event (snapshot, lease, enrolment …); `null` offline or when none. */
+  server: { at: string; action: string; target: string | null } | null;
+  /** The newest of its journal change, server event and presence. */
+  lastActivityAt: string | null;
+}
+
+/** `cleo cloud activity --devices`: one row per device, newest activity first (T13482). */
+export interface CloudDeviceOverviewResult {
+  scope: CloudVaultScope;
+  devices: CloudDeviceOverviewRow[];
+  warnings: CloudWarning[];
+}
+
 /** One conflict an apply recorded (`cleo cloud conflicts`, T12344 PR-6). */
 export interface CloudConflict {
   id: number;

package/src/operations/nexus.ts

@@ -854,6 +854,8 @@ export interface NexusImpactParams {
   why?: boolean;
   /** Maximum reverse traversal depth (default 3, capped at 5). */
   depth?: number;
+  /** `--no-refresh` (T13523): answer from the index as it stands. */
+  noRefresh?: boolean;
 }
 /** Affected symbol in impact result. */
 export interface NexusImpactAffectedNode {
@@ -1203,6 +1205,8 @@ export interface NexusContextParams {
   limit?: number;
   /** When true, fetch source code content. */
   content?: boolean;
+  /** `--no-refresh` (T13523): answer from the index as it stands. */
+  noRefresh?: boolean;
 }
 /** A single caller or callee relationship from `nexus.context`. */
 export interface NexusContextRelation {

package/src/operations/orchestrate.ts

@@ -630,6 +630,13 @@ export interface OrchestrateSpawnResult {
    * @task T963
    */
   sessionId: string | null;
+  /**
+   * The worktree's dependency install outcome (`skipped` under `--no-install`,
+   * `deferred` when the heavy-work budget was busy, with the command the
+   * worker runs instead), or `null` without a worktree.
+   * @task T13524
+   */
+  install?: import('./worktree.js').WorktreeInstallOutcome | null;
   /**
    * Legacy mirror of the prompt/protocolType/tier bundle for readers that
    * still consume `spawnContext.*`.

package/src/operations/validate.ts

@@ -228,6 +228,11 @@ export interface ValidateGateParams {
    * none; a gate without a fresh cached pass refuses with `E_GATE_NOT_CACHED`.
    */
   noRun?: boolean;
+  /**
+   * `--run-typed` (T13521): execute uncached typed gates during this write.
+   * Without it a write reads cached passes only (owner decision).
+   */
+  runTyped?: boolean;
   /**
    * `cleo verify --run --req A,B` (T13486): run and cache only the typed gates
    * with these REQ-IDs (comma-separated); the others are not run.

package/src/operations/worktree.ts

@@ -17,6 +17,7 @@
 // ---------------------------------------------------------------------------
 // Hooks framework
 // ---------------------------------------------------------------------------
+import type { HookExecutor, HookOutcome } from '../project-hooks.js';
 
 /**
  * A declarative lifecycle hook definition for worktree events.
@@ -28,6 +29,8 @@
  * @task T1161
  */
 export interface WorktreeHook {
+  /** Shared hook identity when legacy wiring duplicates a tracked project definition. */
+  projectHookId?: string;
   /** Shell command to run in the worktree dir (`/bin/sh -c` on POSIX, cmd.exe on Windows). */
   command: string;
   /**
@@ -239,6 +242,8 @@ export interface CreateWorktreeOptions {
   reason?: 'subagent' | 'experiment' | 'parallel-wave';
   /** Declarative hooks to run after creation. */
   hooks?: WorktreeHook[];
+  /** Optional shared project executor injected by CLEO; never imports core into worktree. */
+  projectHookExecutor?: HookExecutor;
   /**
    * When true, read `.cleo/worktree-include` from the project root and apply
    * any declared include patterns to the new worktree.
@@ -317,6 +322,50 @@ export interface CreateWorktreeOptions {
    * @task T12506
    */
   lockTtlMs?: number;
+  /**
+   * The git shim the caller installed for this worktree (T13522). Only when
+   * `installed` is the shim dir prepended to PATH and
+   * `CLEO_BRANCH_PROTECTION=strict` advertised; otherwise the env says
+   * `unavailable`, so nothing claims a fence that is not there.
+   *
+   * @task T13522
+   */
+  gitShim?: { readonly dir: string; readonly installed: boolean };
+  /**
+   * Provision without installing dependencies (`--no-install`, T13524). The
+   * result's `install` says so, with the command the worker runs instead.
+   *
+   * @task T13524
+   */
+  skipInstall?: boolean;
+  /**
+   * Admission for the dependency install (T13524): called before `pnpm install`
+   * runs; resolves to a release function once admitted, or `null` when the
+   * machine budget is busy, in which case the install is deferred to the
+   * worker rather than run outside the heavy-work queue. Absent: install
+   * unadmitted (legacy callers).
+   *
+   * @task T13524
+   */
+  admitInstall?: () => Promise<(() => Promise<void>) | null>;
+}
+
+/**
+ * What happened to a worktree's dependency install (T13524).
+ *
+ * @task T13524
+ */
+export interface WorktreeInstallOutcome {
+  /**
+   * `installed`/`failed`: it ran. `skipped`: `--no-install`. `deferred`: the
+   * machine budget was busy, so the worker installs. `not-needed`: no
+   * lockfile, already installed, or a re-attached worktree.
+   */
+  status: 'installed' | 'failed' | 'skipped' | 'deferred' | 'not-needed';
+  /** Why, for anything but `installed`. */
+  reason?: string;
+  /** The command the worker runs when the install did not happen here. */
+  command?: string;
 }
 
 /**
@@ -365,6 +414,8 @@ export interface CreateWorktreeResult {
   preamble: string;
   /** Results of any post-create hooks that were executed. */
   hookResults: WorktreeHookResult[];
+  /** Results from activated project definitions for post-create. */
+  projectHookResults?: HookOutcome[];
   /** Include patterns that were applied (empty if none). */
   appliedPatterns: WorktreeIncludePattern[];
   /**
@@ -378,7 +429,15 @@ export interface CreateWorktreeResult {
     failedPaths: string[];
     /** Results of post-start hooks. */
     hookResults: WorktreeHookResult[];
+    /** Results from activated project definitions for post-start. */
+    projectHookResults?: HookOutcome[];
   };
+  /**
+   * The dependency install outcome (T13524).
+   *
+   * @task T13524
+   */
+  install?: WorktreeInstallOutcome;
 }
 
 // ---------------------------------------------------------------------------

package/src/project-context.ts

@@ -97,6 +97,15 @@ export interface ProjectEvidenceContext {
    * CLEO's own installed hook files are always excluded (T13135, gh#1805).
    */
   scopeExcludes?: string[];
+  /**
+   * Globs of TRACKED files a harness rewrites while a run executes (a goal
+   * runtime's `run.json`, its ledger), left out of the evidence tree hash so
+   * the run cannot stale its own receipt; they stay tracked for history
+   * (T13554). Read from the default branch only. A glob that matches the
+   * project context, a `goal.yaml`, an oracle or a typed gate's input is
+   * refused (E_EVIDENCE_RUNTIME_PATH_PROTECTED). Default: none.
+   */
+  runtimePaths?: string[];
 }
 
 /**

package/src/project-hook-delivery.ts

@@ -0,0 +1,144 @@
+/** Provider delivery contracts; runtime installers live in adapters and CAAMP. */
+import { z } from 'zod';
+import type { HookJsonValue } from './heavy-command-hook.js';
+import type { HookInvocation } from './project-hooks.js';
+
+/** Parsed JSON object used by surgical managed writers. */
+export type HookConfigObject = { readonly [key: string]: HookJsonValue };
+/** One surgical edit; undefined removes exactly the addressed node. */
+export interface HookConfigEdit {
+  /** JSON property/index path. */
+  path: (string | number)[];
+  /** Replacement value, or undefined for removal. */
+  value?: HookJsonValue;
+  /** Append/insert an array element without replacing its siblings. */
+  insert?: boolean;
+}
+/** Receipt authorizing management of one exact config entry. */
+export const ProjectHookDeliveryReceiptSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    provider: z.string().min(1).max(128),
+    configPath: z.string().min(1).max(4096),
+    entries: z
+      .array(
+        z
+          .object({
+            event: z.string().min(1).max(128),
+            hash: z.string().regex(/^[a-f0-9]{64}$/),
+            command: z.string().min(1).max(8192),
+          })
+          .strict(),
+      )
+      .max(128),
+    recordedAt: z.iso.datetime(),
+  })
+  .strict();
+/** Machine-local source and entry ownership receipt. */
+export type ProjectHookDeliveryReceipt = z.infer<typeof ProjectHookDeliveryReceiptSchema>;
+/** Entry-level provenance without printing commands that may contain secrets. */
+export interface ProjectHookEntryInspection {
+  /** Native provider event. */
+  event: string;
+  /** Index in the provider event's entry array. */
+  index: number;
+  /** Receipt proves project delivery ownership; other ownership remains unknown. */
+  owner: 'project' | 'unknown';
+  /** Generated entry is attributable only through its retained local receipt. */
+  provenance: 'cleo-receipt' | 'unknown';
+  /** Entry digest permits review without retaining its command text. */
+  hash: string;
+  /** Tracked source, only for receipt-owned project checks. */
+  source?: '.cleo/hooks.json';
+}
+/** Inspect/install result; a config file never proves native trust or live support. */
+export interface ProjectHookDeliveryResult {
+  /** Harness identifier. */
+  provider: string;
+  /** Observed local binary version, when discoverable. */
+  version?: string;
+  /** Safe resolved project-local destination, absent when unsupported. */
+  configPath?: string;
+  /** Delivery state. */
+  state: 'planned' | 'current' | 'installed' | 'conflict' | 'unsupported' | 'disabled' | 'missing';
+  /** Independent capability evidence. */
+  capability: 'verified' | 'documented' | 'unverified';
+  /** Native project/definition trust is never granted by CLEO. */
+  nativeTrust: 'unverified';
+  /** Receipt-backed provenance; legacy config provenance remains unknown. */
+  provenance: 'cleo-receipt' | 'unknown';
+  /** Sanitized actionable findings. */
+  diagnostics: string[];
+  /** Reviewed team-config integration aid when automatic local delivery is ineligible. */
+  integrationSnippet?: string;
+  /** Per-entry attribution, deliberately excluding raw config command strings. */
+  entries?: ProjectHookEntryInspection[];
+}
+/** SDK-owned utilities injected into provider delivery without a runtime SDK dependency. */
+export interface ProjectHookDeliveryServices {
+  /**
+   * Read bounded regular files through the canonical filesystem primitive.
+   * @remarks
+   * The caller supplies the SDK implementation, preserving special-file and racing-growth checks.
+   * @param path - Resolved file path selected by the delivery adapter.
+   * @param maxBytes - Maximum UTF-8 input size in bytes.
+   * @returns The file's text after its descriptor and allocation limit have been checked.
+   * @example
+   * ```typescript
+   * const readConfiguration = (services: ProjectHookDeliveryServices) =>
+   *   services.readTextFile('/repo/.codex/hooks.json', 262144);
+   * ```
+   */
+  readTextFile(path: string, maxBytes: number): Promise<string>;
+  /**
+   * Git discovery environment with ambient repository overrides removed.
+   * @defaultValue No implicit default; the caller supplies the snapshot.
+   */
+  gitEnvironment: Readonly<Record<string, string | undefined>>;
+}
+/** Explicit cold-path provider sync inputs. */
+export interface ProjectHookDeliveryOptions {
+  /** Canonical SDK utilities supplied by the caller through the contracts port. */
+  services: ProjectHookDeliveryServices;
+  /** Checkout root validated by the core context resolver. */
+  projectRoot: string;
+  /** Per-checkout Git-private receipt directory. */
+  stateDir: string;
+  /** Canonical agent events selected from the manifest. */
+  events: string[];
+  /** Activation was inspected fresh. */
+  enabled: boolean;
+  /** No files (including lock files) may be written in dry-run mode. */
+  dryRun: boolean;
+  /**
+   * Explicit provider selection; otherwise detect project-local configuration.
+   * @defaultValue Providers detected from local configuration and installed harness binaries.
+   */
+  providers?: string[];
+  /**
+   * Remove only receipt-owned, unmodified additions instead of synchronizing.
+   * @defaultValue false
+   */
+  rollback?: boolean;
+}
+
+/** Provider-normalized request awaiting checkout resolution by core. */
+export interface ProjectHookNativeRequest {
+  /** Actual triggering directory, independent of harness-specific environment variables. */
+  cwd: string;
+  /** Provider wire protocol. */
+  provider: string;
+  /** Optional native event name from the provider input. */
+  nativeEvent?: string;
+  /** Shared input fields before Git resolves projectRoot and gitCommonDir. */
+  input: Omit<HookInvocation, 'projectRoot' | 'gitCommonDir'>;
+}
+/** Native stdout/stderr and adapter exit code; never an approval rewrite. */
+export interface ProjectHookNativeResult {
+  /** Provider-format advisory output. */
+  stdout: string;
+  /** Safe current-invocation diagnostics. */
+  stderr: string;
+  /** Git verdict failure or zero for advisory/infra failure. */
+  exitCode: number;
+}