@cleocode/contracts 2026.10.3 → 2026.10.5-rc.ci.672

package/src/nexus-first-run.ts

@@ -0,0 +1,165 @@
+/**
+ * Guided first run of `cleo login nexus` (T13102, owner decision 2026-10-02:
+ * onboarding = A + B + C' + D, so that `cleo login` is the only setup step in
+ * practice).
+ *
+ * After a successful sign-in, login looks at where it runs:
+ *
+ * - Inside a CLEO project this machine has not linked: it offers to link the
+ *   project and take the first encrypted backup. `--yes` does it without asking,
+ *   a terminal asks, and a non-interactive (agent) run never asks: it reports
+ *   the exact next command. When Cleo Nexus already holds a backup of the
+ *   project that this copy never synced (a fresh clone on a new machine), the
+ *   offer is to restore that backup here instead; a backup would be refused.
+ * - Outside a CLEO project: it lists the account's projects, by name, with
+ *   the exact `cleo cloud restore` command for each one that has a backup
+ *   this machine does not hold yet.
+ *
+ * `cleo cloud restore <name>` resolves a project name or label (or an id) to
+ * the server's project id; an ambiguous name lists the candidates.
+ *
+ * This file is types + const data only (arch gate 10).
+ *
+ * @task T13102
+ * @epic T12322
+ */
+
+import type { NexusProjectLink } from './nexus-account.js';
+import type { CloudWarning } from './nexus-cloud.js';
+import type { CloudVaultSnapshot } from './nexus-vault.js';
+
+/**
+ * How the guided first run ended.
+ *
+ * - `backed-up`: the project was linked (or already linked) and its first backup pushed
+ *   (or the cloud already held this exact state).
+ * - `link-failed`: linking failed; nothing was pushed.
+ * - `backup-failed`: the project is linked, but the backup failed.
+ * - `restored`: the cloud held a backup this copy never synced; it was restored here and linked.
+ * - `restore-failed`: restoring that backup failed (for example, local rows it would overwrite).
+ * - `offered`: a non-interactive run inside an unlinked project; nothing was done and
+ *   `nextCommand` says what to run (link and back up, or restore; see `offer`).
+ * - `declined`: the user answered no at the prompt; `nextCommand` says what to run later.
+ * - `already-linked`: the project is linked and attached from this device; nothing to do.
+ * - `projects`: outside a CLEO project; `projects` lists the account's projects.
+ * - `skipped`: the first run does not apply (`reason` says why).
+ */
+export const NEXUS_FIRST_RUN_STATES = [
+  'backed-up',
+  'link-failed',
+  'backup-failed',
+  'restored',
+  'restore-failed',
+  'offered',
+  'declined',
+  'already-linked',
+  'projects',
+  'skipped',
+] as const;
+
+/** One of {@link NEXUS_FIRST_RUN_STATES}. */
+export type NexusFirstRunState = (typeof NEXUS_FIRST_RUN_STATES)[number];
+
+/** Where a project's display name came from. */
+export type NexusProjectNameSource = 'encrypted-name' | 'label' | 'id';
+
+/** One of the account's projects, as the first run and `cleo cloud restore <name>` see it. */
+export interface NexusNamedProject {
+  /** The server's project id (the tracked local project id of whoever linked it). */
+  projectId: string;
+  /**
+   * Display name: the plaintext label, else the id. (`encryptedName` is shown only through a
+   * reader for its format, which cleo-nexus T098 will specify; none is wired in yet.)
+   */
+  name: string;
+  /** Where {@link NexusNamedProject.name} came from. */
+  nameSource: NexusProjectNameSource;
+  /** The plaintext label the server holds, if any. */
+  label: string | null;
+  /** The owning organization's name, when the server sent it. */
+  organizationName: string | null;
+  /** The newest sync over every replica, when the server sent it. */
+  lastSyncAt: string | null;
+  /**
+   * The project's stream holds a snapshot to restore. `null` when the server did not say
+   * (an older server without `headCheckpointId` on the project list).
+   */
+  hasBackup: boolean | null;
+  /** A replica of the project is attached from this device. */
+  onThisDevice: boolean;
+  /**
+   * The exact command that restores it into the current directory, by its id (an id never
+   * changes; for agents and scripts). `null` when there is nothing to restore here (no
+   * backup, or it is already on this device).
+   */
+  restoreCommand: string | null;
+  /**
+   * The same restore by name, for a person to type: set only when the name resolves to this
+   * project alone (and cannot be read as a flag or an id), else `null`.
+   */
+  restoreByNameCommand: string | null;
+}
+
+/** The first backup the guided run pushed. */
+export interface NexusFirstRunBackup {
+  /** `pushed`: a new snapshot; `up-to-date`: the cloud already held this state. */
+  status: 'pushed' | 'up-to-date';
+  /** The snapshot, when the server named one. */
+  snapshot: CloudVaultSnapshot | null;
+}
+
+/** The backup the guided run restored into the project (`restored` only). */
+export interface NexusFirstRunRestore {
+  /** `restored`: the snapshot was activated; `up-to-date`: this copy already held it. */
+  status: 'restored' | 'up-to-date';
+  /** The snapshot, when the server named one. */
+  snapshot: CloudVaultSnapshot | null;
+  /** Tables verified by count and hash. */
+  tables: number;
+  /** The local safety backup taken first, if any. */
+  safetyBackup: string | null;
+}
+
+/**
+ * What the run offered inside an unlinked project: `link-and-backup` (the
+ * project is new to the cloud, or this copy already synced with it), or
+ * `restore` (the cloud holds a backup this copy never synced).
+ */
+export type NexusFirstRunOffer = 'link-and-backup' | 'restore';
+
+/** One option of a choice the first run leaves to the user. */
+export interface NexusFirstRunChoice {
+  /** The exact command. */
+  command: string;
+  /** What it does, in one line. */
+  effect: string;
+}
+
+/** The guided first run's outcome, carried as `data.firstRun` of the `cleo login nexus` envelope. */
+export interface NexusFirstRunResult {
+  /** How it ended. */
+  state: NexusFirstRunState;
+  /** Why it was skipped (`skipped` only), e.g. a read-only device. */
+  reason: string | null;
+  /** The CLEO project login ran in, or `null` outside one. */
+  projectRoot: string | null;
+  /** The project's link after the run, when it is linked. */
+  link: NexusProjectLink | null;
+  /** What was offered inside an unlinked project, or `null` elsewhere. */
+  offer: NexusFirstRunOffer | null;
+  /** The backup pushed (`backed-up` only). */
+  backup: NexusFirstRunBackup | null;
+  /** The backup restored (`restored` only). */
+  restore: NexusFirstRunRestore | null;
+  /** The account's projects (`projects` only), newest first. */
+  projects: NexusNamedProject[];
+  /** The exact command to run next, when there is one (never asks: agents run it). */
+  nextCommand: string | null;
+  /**
+   * When the next step is a choice only the user can make (`nextCommand` is `null`), each
+   * option as `{ command, effect }`; empty otherwise.
+   */
+  choices: NexusFirstRunChoice[];
+  /** Non-fatal problems met on the way (secret-free). */
+  warnings: CloudWarning[];
+}

package/src/nexus-vault.ts

@@ -46,6 +46,38 @@ export const nexusProjectKeysSchema = z.looseObject({
   ),
 });
 
+// ---------- wire: replica retirement refusals (cleo-nexus T123) ----------
+
+/**
+ * The `details.reason` values E31 (`POST …/replicas/:replicaId/retirements`) and the calls it guards answer with
+ * (cleo-nexus #41, contract v2.28):
+ * - `not-pinned-or-owner` (403): the caller is neither the replica's pinned device nor, on a project stream, an
+ *   owner's device (on a home stream, any device of the account may retire).
+ * - `retire-below-head` (409): `lastReplicaSeq` is under the replica's highest appended replicaSeq, or null while
+ *   the replica has a segment.
+ * - `retired` (409): the replica is already retired with another successor or `lastReplicaSeq` (the same pair
+ *   again answers 200 with the stored record).
+ * - `successor-other-user` (403): on a project stream, the successor is pinned to another user's device.
+ * - `successor-taken` (409): another user's retirement already names that successor.
+ * - `successor-retired` (409): the successor is itself retired (this also refuses a cycle).
+ * - `replica-retired` (409, `E_CONFLICT`, with `lastReplicaSeq` and `successor`): a segment append past the
+ *   retirement, or a lease request, for a retired replica.
+ * The server's strings, not a cloud wire schema: kept here, beside the vault's other wire constants, so the
+ * `@cleocode/contracts/cloud` mirror stays byte-for-byte the server's.
+ */
+export const NEXUS_REPLICA_RETIREMENT_REASONS = [
+  'not-pinned-or-owner',
+  'retire-below-head',
+  'retired',
+  'successor-other-user',
+  'successor-taken',
+  'successor-retired',
+  'replica-retired',
+] as const;
+
+/** One E31 refusal reason ({@link NEXUS_REPLICA_RETIREMENT_REASONS}). */
+export type NexusReplicaRetirementReason = (typeof NEXUS_REPLICA_RETIREMENT_REASONS)[number];
+
 // ---------- wire: leases (cleo-nexus T083) ----------
 
 /** The lease role of the vault's single writer. */
@@ -195,15 +227,59 @@ export interface CloudRestoreResult {
   tables: number;
   /** Local safety backup taken before activation, if any. */
   safetyBackup: string | null;
+  /**
+   * The placed file is a new store instance, so the replica this store had is
+   * retired and a new one bound (journal spec §1.5; T13109). The server keeps
+   * the retired one as history until S4 announces its retirement. `null` when
+   * nothing was placed or the store had no replica yet (a first restore here).
+   *
+   * `reason` is `vault-restore` when the retired replica was this device's
+   * replica of the replaced file (recorded as a retire candidate unless the
+   * registry write failed), `file-identity` or `foreign-device` when the store
+   * was a copy or another device's (the carried replica stays live where it
+   * belongs; nothing to retire), and `null` when the rebind's registry write
+   * failed.
+   */
+  replica: {
+    retired: string;
+    current: string;
+    reason: 'vault-restore' | 'file-identity' | 'foreign-device' | null;
+  } | null;
   warnings: CloudWarning[];
 }
 
+/**
+ * `cleo cloud verify --deep` (T13291): the cloud copy downloaded again and
+ * checked byte for byte. Local backups are checked by `cleo backup verify`.
+ */
+export interface CloudVerifyDeepCheck {
+  /**
+   * The head snapshot and each device's newest snapshot: its bundle downloaded,
+   * checked against the size and sha256 its signed checkpoint records, and
+   * decrypted. `problem` says why a check failed; `null` when it passed.
+   */
+  snapshots: Array<{
+    checkpointId: string;
+    deviceId: string;
+    sizeBytes: number;
+    ok: boolean;
+    problem: string | null;
+  }>;
+  /**
+   * The journal segments after the head snapshot (from the start of the stream
+   * when there is none), each re-hashed, signature-checked and decrypted.
+   * `from` is the stream seq they start after; `checked` counts the segments
+   * that passed; `problem` is the first failure, `null` when none.
+   */
+  segments: { from: number; checked: number; ok: boolean; problem: string | null };
+}
+
 /** `cleo cloud verify`. */
 export interface CloudVerifyResult {
   apiUrl: string;
   scope: CloudVaultScope;
   streamId: string;
-  /** `match`: local equals the head snapshot; `ahead`: local changed since this machine's last snapshot; `behind`: the cloud has a newer snapshot; `diverged`: both; `empty`: no snapshot yet; `untrusted`: the head snapshot's signature does not verify against a trusted device key (nothing is compared with it). */
+  /** `match`: local equals the head snapshot; `ahead`: local changed since this machine's last snapshot; `behind`: the cloud has a newer snapshot; `diverged`: both; `empty`: no snapshot yet; `untrusted`: the head snapshot's signature does not verify against a trusted device key (nothing is compared with it), or with `--deep`, its bundle or a segment after it failed the byte check. */
   verdict: 'match' | 'ahead' | 'behind' | 'diverged' | 'empty' | 'untrusted';
   /** What to do about a verdict other than `match` (or a failed integrity check); `null` when nothing. */
   remedy: string | null;
@@ -222,6 +298,8 @@ export interface CloudVerifyResult {
     createdAt: string | null;
     matchesHead: boolean;
   }>;
+  /** The byte-level check of `--deep`; absent without it. */
+  deep?: CloudVerifyDeepCheck;
   warnings: CloudWarning[];
 }
 
@@ -278,3 +356,48 @@ export interface CloudActivityResult {
   nextBefore: string | null;
   warnings: CloudWarning[];
 }
+
+/** One conflict an apply recorded (`cleo cloud conflicts`, T12344 PR-6). */
+export interface CloudConflict {
+  id: number;
+  stream: string;
+  seq: number;
+  txnIdx: number;
+  /** Op index in the transaction; -1 for a whole-transaction (post-apply) conflict. */
+  opIdx: number;
+  /** `field`, `typed-rule`, `edit-vs-delete`, `delete-vs-edit`, `dangling-ref`, `guard`, `delete-with-live-children`, `uid-collision`, `post-apply` … */
+  kind: string;
+  table: string;
+  uid: string;
+  columns: string[];
+  /** The typed rule, guard message or invariant, when there is one. */
+  rule: string | null;
+  /** What happened to the incoming op: `incoming-applied`, `incoming-dropped`, `row-deleted`, `op-voided`. */
+  resolution: string;
+  opHlc: string;
+  localHlc: string | null;
+  /** The replica that wrote the op. */
+  origin: string;
+  createdAt: string;
+  resolvedAt: string | null;
+}
+
+/** `cleo cloud conflicts`: the store's recorded sync conflicts. */
+export interface CloudConflictsResult {
+  scope: CloudVaultScope;
+  /** Unresolved conflicts in the store. */
+  open: number;
+  /** All conflicts in the store. */
+  total: number;
+  conflicts: CloudConflict[];
+  warnings: CloudWarning[];
+}
+
+/** `cleo cloud conflicts resolve <id>`. */
+export interface CloudConflictResolveResult {
+  scope: CloudVaultScope;
+  id: number;
+  /** False when no open conflict has that id. */
+  resolved: boolean;
+  warnings: CloudWarning[];
+}

package/src/operations/admin.ts

@@ -108,6 +108,10 @@ export interface AdminBackupEntry {
   note?: string;
   /** File names captured in this backup. */
   files: string[];
+  /** Which store it is of: `project` (`.cleo/cleo.db`) or `global` (`<CLEO_HOME>/cleo.db`, T13245). */
+  scope?: 'project' | 'global';
+  /** What its store file holds: `tasks`, `brain`, `conduit` (project) or `global` (T13245). */
+  contains?: string[];
 }
 
 /**
@@ -1194,7 +1198,10 @@ export type AdminAdrShowResult = AdminAdrRecord;
 // ---------------------------------------------------------------------------
 
 /** Parameters for `admin.backup` query — none required. */
-export type AdminBackupListParams = Record<string, never>;
+export interface AdminBackupListParams {
+  /** `project`, `global` or `all` (default `all`; T13245). */
+  scope?: 'project' | 'global' | 'all';
+}
 
 /** Result of `admin.backup` query. */
 export interface AdminBackupListResult {
@@ -1653,6 +1660,10 @@ export interface AdminBackupMutateParams {
    * project's live store (T12680). Without it such a restore is refused.
    */
   confirmOwnerStore?: boolean;
+  /** Create: also back up the global store (`<CLEO_HOME>/cleo.db`, T13245). */
+  includeGlobal?: boolean;
+  /** Restore by id: `global` restores a backup of the global store (T13245). */
+  scope?: 'project' | 'global';
 }
 
 /** Result of `admin.backup` mutate (create action). */
@@ -1667,6 +1678,8 @@ export interface AdminBackupCreateResult {
   type: string;
   /** Files captured in the backup. */
   files: string[];
+  /** The global store's backup, when `includeGlobal` was set (T13245). */
+  global?: AdminBackupCreateResult | null;
 }
 
 /** Result of `admin.backup` mutate (restore action — by ID). */

package/src/operations/conduit.ts

@@ -97,7 +97,7 @@ export interface ConduitStatusResult {
 }
 
 // --------------------------------------------------------------------------
-// conduit.peek → one-shot poll for new messages (ACKs as it reads)
+// conduit.peek → one-shot poll for new messages (never acks or consumes, T13169)
 // --------------------------------------------------------------------------
 
 /** Parameters for `conduit.peek`. */

package/src/operations/docs-lifecycle.ts

@@ -0,0 +1,31 @@
+/**
+ * Lifecycle statuses of a canonical doc.
+ *
+ * A leaf module with no schema imports: the operation registry
+ * (`dispatch/operations-registry.ts`) and the dispatch input sanitizer read
+ * these on every command, and `./docs.js` imports zod for its payload schemas.
+ * `./docs.js` re-exports both names.
+ *
+ * @task T10161
+ * @task T13126 - split out of operations/docs.ts
+ */
+
+/**
+ * Allowed `lifecycle_status` values mirrored from the attachments-table enum
+ * (`ATTACHMENT_LIFECYCLE_STATUSES` in
+ * `packages/core/src/store/schema/attachments.ts`). Kept inline here so the
+ * contract surface stays self-contained — the dispatch handler narrows raw
+ * `--status` input against this set before touching the store.
+ *
+ * @task T10161 (Epic T10157 / Saga T9855)
+ */
+export const DOCS_LIFECYCLE_STATUSES = [
+  'draft',
+  'proposed',
+  'accepted',
+  'superseded',
+  'archived',
+  'deprecated',
+] as const;
+
+export type DocsLifecycleStatus = (typeof DOCS_LIFECYCLE_STATUSES)[number];

package/src/operations/docs.ts

@@ -39,6 +39,7 @@ import type {
   OperationExecutionIdentity,
 } from '../jobs.js';
 import type { DocAttachmentObservationPayload } from '../memory/observe.js';
+import type { DocsLifecycleStatus } from './docs-lifecycle.js';
 
 // ============================================================================
 // Shared Attachment Types (API wire format)
@@ -686,25 +687,9 @@ export interface DocsRemoveResult {
 // docs.update — UPDATE-in-place via slug (T10161)
 // --------------------------------------------------------------------------
 
-/**
- * Allowed `lifecycle_status` values mirrored from the attachments-table enum
- * (`ATTACHMENT_LIFECYCLE_STATUSES` in
- * `packages/core/src/store/schema/attachments.ts`). Kept inline here so the
- * contract surface stays self-contained — the dispatch handler narrows raw
- * `--status` input against this set before touching the store.
- *
- * @task T10161 (Epic T10157 / Saga T9855)
- */
-export const DOCS_LIFECYCLE_STATUSES = [
-  'draft',
-  'proposed',
-  'accepted',
-  'superseded',
-  'archived',
-  'deprecated',
-] as const;
-
-export type DocsLifecycleStatus = (typeof DOCS_LIFECYCLE_STATUSES)[number];
+// The lifecycle statuses live in `./docs-lifecycle.js`, a leaf without zod: the
+// operation registry reads them on every dispatch (T13126).
+export { DOCS_LIFECYCLE_STATUSES, type DocsLifecycleStatus } from './docs-lifecycle.js';
 
 /**
  * Parameters for `docs.update`.

package/src/project-context.ts

@@ -90,6 +90,13 @@ export interface ProjectEvidenceContext {
     /** Job-name globs that must have run and succeeded for a code task's gate. */
     jobs?: { tests?: string[]; qa?: string[] };
   };
+  /**
+   * Repo-relative paths or globs (`path.matchesGlob`, `**` crosses directories)
+   * that never count as part of a change when evidence decides its scope —
+   * runtime state a tool writes into the checkout, e.g. `.opencode/goals/**`.
+   * CLEO's own installed hook files are always excluded (T13135, gh#1805).
+   */
+  scopeExcludes?: string[];
 }
 
 /**
@@ -126,10 +133,18 @@ export interface ProjectContext {
     command?: string;
     /**
      * Affected-scope test command template for `tool:test-affected` (D11150,
-     * T12635): `{projects}`, `{filters}` and `{packages}` expand per affected
-     * package, e.g. `pnpm exec vitest run {projects}`.
+     * T12635) and a scope-aware `tool:test` (T12959): `{projects}`,
+     * `{filters}`, `{workspaces}` and `{packages}` expand per affected
+     * package, e.g. `pnpm exec vitest run {projects}`. When absent, one is
+     * derived from a workspace-wide `command` where that is mechanical
+     * (`pnpm -r … test`, `npm … test --workspaces`, `turbo run test`; T13125).
      */
     affectedCommand?: string;
+    /**
+     * `false` makes `tool:test` always run the full suite instead of the
+     * affected scope (T12959).
+     */
+    preferAffected?: boolean;
     testFilePatterns?: string[];
     directories?: {
       unit?: string;

package/src/release/evidence-atoms.ts

@@ -136,26 +136,30 @@ export const ghPrViewSchema = z
 export type GhPrViewPayload = z.infer<typeof ghPrViewSchema>;
 
 /**
- * Default required-workflow names enforced by `pr:<number>` validation.
- *
- * Mirrors the canonical branch-protection list documented in
- * `docs/release/branch-protection-setup.md`. Override via
- * {@link PR_REQUIRED_WORKFLOWS_ENV_VAR} when projects deviate (e.g. an
- * out-of-tree consumer with different gating workflows).
+ * cleocode's OWN required-check names: the `CI` aggregate of its ci.yml and the
+ * `Contracts Dep Lint` job, both real check names there (T13285; a test pins
+ * every name to a job or workflow in cleocode's `.github/workflows/`).
+ *
+ * This is cleocode's configuration, not a library default for other
+ * repositories. Since gh#1323 the evidence path (`resolveRequiredWorkflowsDetailed`)
+ * never applies it to another repository: with no env override, no
+ * `release.prRequiredWorkflows` in `.cleo/project-context.json` and no readable
+ * branch protection it returns tier `unknown` and refuses loudly. Only the
+ * synchronous `resolveRequiredWorkflows` still returns it as its last tier.
+ * cleocode itself resolves through its project-context entry. (`Lockfile Check`
+ * was dropped: no check ever reported under that name — its job is
+ * "Verify pnpm-lock.yaml consistency" — and CI now covers it, T13279.)
  *
  * @task T9764
+ * @task T13285
  */
-export const PR_REQUIRED_WORKFLOWS: readonly string[] = Object.freeze([
-  'CI',
-  'Lockfile Check',
-  'Contracts Dep Lint',
-]);
+export const PR_REQUIRED_WORKFLOWS: readonly string[] = Object.freeze(['CI', 'Contracts Dep Lint']);
 
 /**
  * Name of the env var that overrides {@link PR_REQUIRED_WORKFLOWS}.
  *
  * Format: comma-separated workflow names (e.g.
- * `"CI,Lockfile Check,MyExtraGate"`). Whitespace around commas is
+ * `"CI,Contracts Dep Lint,MyExtraGate"`). Whitespace around commas is
  * trimmed.
  *
  * @task T9764

package/src/resource-governor.ts

@@ -88,6 +88,41 @@ export const RUN_DEFERRED_EXIT_CODE = 75;
  */
 export const RESOURCE_BACKPRESSURE_CODE = 'E_RESOURCE_BACKPRESSURE' as const;
 
+/**
+ * The numbers behind a memory-pressure refusal of a heavy class (T13127).
+ *
+ * The memory gate refuses `test-run`, `scoped-build` and `full-build` while
+ * memory pressure is above {@link MemoryPressureReading.refuseAbove}; once it
+ * has refused, it admits again only when pressure falls to
+ * {@link MemoryPressureReading.resumeAtOrBelow} (hysteresis), so admission
+ * does not flap at the threshold.
+ *
+ * @example
+ * ```ts
+ * const r: MemoryPressureReading = {
+ *   score: 31, fullStall: 0, refuseAbove: 25, resumeAtOrBelow: 15, latched: false,
+ *   memAvailableBytes: 21_000_000_000,
+ *   summary: 'kernel level warn; 59% of RAM wired or compressed; swap 11.4 GiB used (24% of RAM)',
+ * };
+ * ```
+ */
+export interface MemoryPressureReading {
+  /** Memory pressure on the PSI `some avg10` scale (0–100). */
+  readonly score: number;
+  /** Memory `full avg10` stall (0–100); 0 when the platform reports none. */
+  readonly fullStall: number;
+  /** Heavy classes are refused while {@link score} is above this. */
+  readonly refuseAbove: number;
+  /** A refusing gate admits again once {@link score} is at or below this. */
+  readonly resumeAtOrBelow: number;
+  /** `true` when the gate was already refusing, so the resume threshold applied. */
+  readonly latched: boolean;
+  /** Available memory in bytes, when the platform reports it. */
+  readonly memAvailableBytes: number | null;
+  /** The platform signals in one line (kernel level, swap, compressor, PSI). */
+  readonly summary: string;
+}
+
 /**
  * Structured, retryable deferral returned when admission is denied. Never a
  * silent drop; callers back off `retryAfterMs` and re-request, or annotate the
@@ -102,6 +137,11 @@ export interface ResourceDeferral {
   readonly retryAfterMs: number;
   /** Human-readable reason (pressure state, budget, held count). */
   readonly reason: string;
+  /**
+   * Set when the deferral is a memory-pressure refusal of a heavy class rather
+   * than a full budget: the readings behind it (T13127).
+   */
+  readonly memoryPressure?: MemoryPressureReading;
 }
 
 /**
@@ -139,6 +179,66 @@ export function isResourceGrant(r: AdmissionResult): r is ResourceGrant {
   return r.deferred === false;
 }
 
+/**
+ * Where the heap ceiling of a heavy tool run came from (T13122).
+ *
+ * - `default` — no heap in the caller's `NODE_OPTIONS`; CLEO's default applies.
+ * - `inherited` — the caller's `NODE_OPTIONS` heap fits the run's budget and is
+ *   kept; the worker count shrinks so the run still fits.
+ * - `clamped` — the caller's `NODE_OPTIONS` heap exceeds the run's budget (a
+ *   shell-profile export is not a per-project choice) and was lowered to it.
+ * - `override` — `CLEO_HEAVY_HEAP_MB` set it explicitly; never clamped.
+ */
+export type HeavyHeapSource = 'default' | 'inherited' | 'clamped' | 'override';
+
+/** One inherited environment value CLEO replaced because it exceeded the plan (T13122). */
+export interface HeavyLeverChange {
+  /** Variable name, e.g. `VITEST_MAX_WORKERS` or `NODE_OPTIONS`. */
+  readonly name: string;
+  /** The inherited value, as the caller's environment carried it. */
+  readonly from: string;
+  /** The value the tool was spawned with. */
+  readonly to: string;
+}
+
+/**
+ * The resource plan a memory-bound tool (`test`, `build`, and since T13123
+ * `typecheck`, `lint`) was spawned with, and why (T13122). Reported by
+ * `cleo verify` (on the `tool` evidence atom and in a resource-kill message)
+ * and by `cleo run`, so an operator can see when an inherited value was
+ * clamped. A single-process tool's plan has one worker.
+ *
+ * The invariant it describes: `workspaceConcurrency × workers × heapMb` stays
+ * within `budgetMb`, unless an explicit `CLEO_HEAVY_*` override asked for more
+ * (`overBudget`).
+ */
+export interface HeavyToolResourcePlan {
+  /** V8 old-space ceiling given to every Node process in the tool's tree, in MiB. */
+  readonly heapMb: number;
+  /** Where {@link heapMb} came from. */
+  readonly heapSource: HeavyHeapSource;
+  /** The heap the caller's `NODE_OPTIONS` asked for, in MiB; `null` when it set none. */
+  readonly inheritedHeapMb: number | null;
+  /** Worker count given to every runner that reads one (`VITEST_MAX_WORKERS`, `GOMAXPROCS`, …). */
+  readonly workers: number;
+  /** `plan` when derived from the heap and budget; `override` when `CLEO_HEAVY_WORKERS` set it. */
+  readonly workersSource: 'plan' | 'override';
+  /** Workspace packages allowed to run their script at once (`npm_config_workspace_concurrency`). */
+  readonly workspaceConcurrency: number;
+  /** Heap budget for the whole run, in MiB: the default worker count times the default heap. */
+  readonly budgetMb: number;
+  /** Total RAM the budget derives from, in MiB. */
+  readonly totalRamMb: number;
+  /** Inherited values replaced because they exceeded the plan. Empty when nothing was clamped. */
+  readonly clamped: readonly HeavyLeverChange[];
+  /** Inherited worker or concurrency values kept because they were within the plan, as `NAME=value`. */
+  readonly kept: readonly string[];
+  /** `true` when explicit `CLEO_HEAVY_*` overrides put the run over {@link budgetMb}. */
+  readonly overBudget: boolean;
+  /** One line naming the heap and worker count chosen and why. */
+  readonly summary: string;
+}
+
 /** Explicit local user-manager connection for resource-controlled process launch. */
 export interface SystemdControlContext {
   /** Absolute existing runtime directory used only by the manager probe and launcher. */