@cleocode/contracts 2026.10.3 → 2026.10.4

package/src/heavy-command-hook.ts

@@ -19,9 +19,10 @@
  *
  * - `rewrite` — DEFAULT. Wrap it in place as
  *   `cleo run --wait --passthrough --class <c> -- <cmd>`, when the harness
- *   runs in `bypassPermissions` or `auto` mode and no deny or ask rule names
- *   the command (otherwise the hook warns: a rewrite would change which
- *   permission rules match).
+ *   runs in `bypassPermissions` or `auto` mode, or (Claude Code `default`,
+ *   `acceptEdits`, `dontAsk`) when the user's allow rules already approve the
+ *   command, and no deny or ask rule names it. Otherwise the hook warns: a
+ *   rewrite would change which permission rules match.
  * - `warn` — leave the command alone; add a context line naming the governed
  *   form.
  * - `off` — do nothing (the installer also removes the hook entry).
@@ -124,9 +125,13 @@ export interface OpencodeHeavyCommandAnswer {
 export interface PreToolUseHookOutput {
   readonly hookSpecificOutput: {
     readonly hookEventName: 'PreToolUse';
-    /** Omitted unless the provider requires it (Codex rewrites need `allow`). */
+    /**
+     * Omitted unless needed: Codex rewrites need `allow`, Kimi's "re-run it"
+     * is a `deny`, and a Claude Code rewrite carries `allow` only when the
+     * user's allow rules already approve the original command (T13124).
+     */
     readonly permissionDecision?: 'allow' | 'deny';
-    /** Shown to the agent on `deny`. */
+    /** Shown to the agent on `deny`; written to Claude Code's debug log on `allow`. */
     readonly permissionDecisionReason?: string;
     /** Replaces the whole tool input. */
     readonly updatedInput?: ShellToolInput;
@@ -134,3 +139,168 @@ export interface PreToolUseHookOutput {
     readonly additionalContext?: string;
   };
 }
+
+// ---------------------------------------------------------------------------
+// Project-level delivery (T13124)
+// ---------------------------------------------------------------------------
+
+/**
+ * What delivering the hook to one provider did in one project.
+ *
+ * - `installed` / `updated` / `removed` / `unchanged` — the config file was
+ *   written, refreshed, cleaned (mode `off`) or already current.
+ * - `skipped` — not applicable: the provider is not in use on this machine or
+ *   project, or the project is the user's home directory (whose provider
+ *   configs are user-global, which CLEO never writes).
+ * - `blocked` — a path the hook must live under exists but is not a
+ *   directory (a stray `.codex` file, say); nothing was written.
+ * - `unsupported` — the provider cannot take a project-level hook (Kimi reads
+ *   hooks only from its global config).
+ * - `needs-consent` — the config is the project's own (Codex's committable
+ *   `.codex/hooks.json`, tracked or holding anything CLEO did not write), so
+ *   CLEO does not write or hide it; `snippet` is the entry to add by hand.
+ * - `failed` — any other error, such as a config file that is not valid JSON
+ *   (left untouched).
+ */
+export type HeavyHookDeliveryStatus =
+  | 'installed'
+  | 'updated'
+  | 'removed'
+  | 'unchanged'
+  | 'skipped'
+  | 'blocked'
+  | 'unsupported'
+  | 'needs-consent'
+  | 'failed';
+
+/** One provider's result from syncing the hook into a project. */
+export interface HeavyHookDeliveryOutcome {
+  /** The harness. */
+  readonly provider: HeavyCommandHookProvider;
+  /** What the sync did. */
+  readonly status: HeavyHookDeliveryStatus;
+  /** The config file (or plugin file) the hook lives in, absolute. */
+  readonly target: string;
+  /** Why it was skipped, blocked, unsupported or failed. */
+  readonly reason?: string;
+  /** The exact step that fixes a `blocked`, `unsupported`, `needs-consent` or `failed` outcome. */
+  readonly remedy?: string;
+  /** `needs-consent`: the exact JSON entry to add to the config by hand. */
+  readonly snippet?: string;
+}
+
+/**
+ * The hook's state for one provider in one project, as `cleo doctor` reports it.
+ *
+ * - `installed` — present and identical to what this CLEO would write.
+ * - `outdated` — present but written by another CLEO build, only in a legacy
+ *   location, or visible to git as an untracked file (gh#1805: it widens
+ *   `cleo verify`'s evidence scope); `cleo upgrade` refreshes it.
+ * - `missing` — the provider is in use and the hook is absent.
+ * - `blocked` — see {@link HeavyHookDeliveryStatus}.
+ * - `unreadable` — the config file exists but cannot be read or parsed.
+ * - `unsupported` — the provider cannot take a project-level hook.
+ * - `needs-consent` — see {@link HeavyHookDeliveryStatus}; `snippet` holds the entry.
+ * - `disabled` — `resources.heavyCommandHook` is `off`, and no CLEO hook is left.
+ * - `not-detected` — the provider is not in use here; nothing is expected.
+ */
+export type HeavyHookInstallState =
+  | 'installed'
+  | 'outdated'
+  | 'missing'
+  | 'blocked'
+  | 'unreadable'
+  | 'unsupported'
+  | 'needs-consent'
+  | 'disabled'
+  | 'not-detected';
+
+/** One provider's hook state in one project. */
+export interface HeavyHookInspection {
+  /** The harness. */
+  readonly provider: HeavyCommandHookProvider;
+  /** Whether the provider is in use on this machine or in this project. */
+  readonly detected: boolean;
+  /** The hook's state. */
+  readonly state: HeavyHookInstallState;
+  /** The config file (or plugin file) the hook lives in, absolute. */
+  readonly target: string;
+  /** One line saying what was found. */
+  readonly detail: string;
+  /** The exact step that fixes the state, when one is needed. */
+  readonly remedy?: string;
+  /** `needs-consent`: the exact JSON entry to add to the config by hand. */
+  readonly snippet?: string;
+}
+
+/**
+ * Whether the `cleo` a hook finds on PATH can answer it.
+ *
+ * - `current` — it answers `cleo hook heavy-command`.
+ * - `older` — it predates `cleo hook` (and `cleo run`): the hook lets every
+ *   command run ungoverned. The hook's own marker (exit 127, "Unknown
+ *   command") or a direct probe says so.
+ * - `missing` — no `cleo` on PATH: the hook stays silent.
+ * - `unknown` — the probe failed some other way (a broken version-manager
+ *   shim, a timeout, a crash). The hook fails open, so it governs nothing
+ *   while this lasts.
+ */
+export type HeavyHookCliState = 'current' | 'older' | 'missing' | 'unknown';
+
+/** The result of probing the `cleo` on PATH from a project directory. */
+export interface HeavyHookCliProbe {
+  /** What the probe found. */
+  readonly state: HeavyHookCliState;
+  /** The `cleo` the hook resolves on PATH, or `null`. */
+  readonly path: string | null;
+  /** One line saying what was found. */
+  readonly detail: string;
+  /** The exact step that fixes (or diagnoses) a CLI that is not `current`. */
+  readonly remedy?: string;
+}
+
+/** Options for the project-level delivery functions (all injectable for tests). */
+export interface HeavyHookDeliveryOptions {
+  /** Environment for provider detection (`PATH`, `HOME`, `CODEX_HOME`, …). Default `process.env`. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Providers to consider. Default: every provider CLEO knows. */
+  readonly providers?: readonly HeavyCommandHookProvider[];
+  /**
+   * Inspection only: run the git checks (a hook file git can see, a shared
+   * Codex `hooks.json`). Default `true`; the session briefing passes `false`
+   * to skip their git spawns (`cleo doctor` keeps them).
+   */
+  readonly gitChecks?: boolean;
+}
+
+/**
+ * The project-level delivery surface `@cleocode/adapters` exports at
+ * `@cleocode/adapters/heavy-command-hook`. `@cleocode/core` loads it at run
+ * time (adapters builds on core, so core cannot import it statically) for
+ * `cleo init`, `cleo upgrade`, `cleo doctor` and the session briefing.
+ */
+export interface HeavyHookDeliveryApi {
+  /**
+   * Install, refresh or (mode `off`) remove CLEO's hook for every provider in
+   * use, each independently. Never throws: every provider gets an outcome.
+   */
+  readonly syncProjectHeavyCommandHooks: (
+    projectDir: string,
+    mode: HeavyCommandHookMode,
+    options?: HeavyHookDeliveryOptions,
+  ) => Promise<readonly HeavyHookDeliveryOutcome[]>;
+  /** Read-only: the hook's state for every provider. Never throws. */
+  readonly inspectProjectHeavyCommandHooks: (
+    projectDir: string,
+    mode: HeavyCommandHookMode,
+    options?: HeavyHookDeliveryOptions,
+  ) => readonly HeavyHookInspection[];
+  /**
+   * Whether the `cleo` on PATH (as the hook resolves it from `projectDir`)
+   * can answer the hook. Starts that `cleo` once. Never throws.
+   */
+  readonly probeHeavyHookCli: (
+    projectDir: string,
+    options?: HeavyHookDeliveryOptions,
+  ) => HeavyHookCliProbe;
+}

package/src/index.ts

@@ -780,6 +780,14 @@ export type {
   HeavyCommandHookProvider,
   HeavyCommandPlan,
   HeavyCommandSegment,
+  HeavyHookCliProbe,
+  HeavyHookCliState,
+  HeavyHookDeliveryApi,
+  HeavyHookDeliveryOptions,
+  HeavyHookDeliveryOutcome,
+  HeavyHookDeliveryStatus,
+  HeavyHookInspection,
+  HeavyHookInstallState,
   HookJsonValue,
   OpencodeHeavyCommandAnswer,
   PreToolUseHookInput,
@@ -2270,6 +2278,9 @@ export * from './render/index.js';
 export type {
   AdmissionResult,
   GovernorMode,
+  HeavyHeapSource,
+  HeavyLeverChange,
+  HeavyToolResourcePlan,
   ResourceClass,
   ResourceDeferral,
   ResourceGrant,
@@ -3009,6 +3020,8 @@ export type {
   NexusAccountErrorCode,
   NexusAccountMe,
   NexusAccountOrganization,
+  NexusAccountSetup,
+  NexusAccountSetupStep,
   NexusAccountStatus,
   NexusAccountUser,
   NexusDeviceEndOutcome,
@@ -3092,6 +3105,18 @@ export {
   nexusCloudUserSchema,
   nexusCloudWhoamiSchema,
 } from './nexus-cloud.js';
+// === Guided first run of `cleo login nexus` (T13102) ===
+export {
+  NEXUS_FIRST_RUN_STATES,
+  type NexusFirstRunBackup,
+  type NexusFirstRunChoice,
+  type NexusFirstRunOffer,
+  type NexusFirstRunRestore,
+  type NexusFirstRunResult,
+  type NexusFirstRunState,
+  type NexusNamedProject,
+  type NexusProjectNameSource,
+} from './nexus-first-run.js';
 export {
   type CloudActivityItem,
   type CloudActivityResult,

package/src/nexus-account.ts

@@ -101,6 +101,11 @@ export const NEXUS_ACCOUNT_ERROR_CODES = [
   'E_NEXUS_VAULT_STORE_BUSY',
   /** A project restore target already holds a different project. */
   'E_NEXUS_VAULT_TARGET_OCCUPIED',
+  // Projects by name (`cleo cloud restore <name>`, T13102).
+  /** No project of the account has that name, label or id. */
+  'E_NEXUS_PROJECT_NOT_FOUND',
+  /** Several of the account's projects have that name or label; the error lists them. */
+  'E_NEXUS_PROJECT_AMBIGUOUS',
 ] as const;
 
 /** One of {@link NEXUS_ACCOUNT_ERROR_CODES}. */
@@ -181,6 +186,72 @@ export interface NexusLoginDevice {
   created: boolean | null;
 }
 
+/**
+ * A step of the account setup `cleo login nexus` runs right after enrolment
+ * (T13100), named when it fails:
+ *
+ * - `connect`: open the vault connection with the new device credential;
+ * - `escrow-read`: read the escrowed account master key (`GET /v1/account/keys/escrow`);
+ * - `escrow-mint`: on the account's first device, create the master key and escrow it
+ *   (`PUT /v1/account/keys/escrow`; a 409 means another device won, and its key is read);
+ * - `certify`: certify this device under the master key (`PUT /v1/devices/:id/key`);
+ * - `trust`: evaluate and record the signer trust state (`GET /v1/devices/trust`,
+ *   `<cleoHome>/nexus-vault.json`).
+ */
+export type NexusAccountSetupStep = 'connect' | 'escrow-read' | 'escrow-mint' | 'certify' | 'trust';
+
+/**
+ * What `cleo login nexus` did to make the account ready for encrypted backups
+ * (T13100). Holds no key.
+ *
+ * - `ready`: this device holds the account master key and is certified under it;
+ * - `unsupported`: the server has no account key escrow; the login still succeeded;
+ * - `skipped`: a read-only device, which never mints or certifies;
+ * - `failed`: the login succeeded but the setup did not; `step` and `fix` say where and what to do.
+ */
+export type NexusAccountSetup =
+  | {
+      status: 'ready';
+      /**
+       * `fetched`: the escrowed key was opened; `minted`: this device created and escrowed it;
+       * `adopted`: another device escrowed first (409) and its key was read, never re-minted.
+       */
+      escrow: 'fetched' | 'minted' | 'adopted';
+      /** `new`: this login certified the device; `existing`: it already was. */
+      certificate: 'new' | 'existing';
+      /** Version of the account master key. */
+      keyVersion: number;
+      /** One human line. */
+      summary: string;
+    }
+  | {
+      status: 'unsupported';
+      /** `E_NEXUS_VAULT_UNSUPPORTED`. */
+      code: NexusAccountErrorCode;
+      /** The remedy. */
+      fix: string;
+      /** One human line. */
+      summary: string;
+    }
+  | {
+      status: 'skipped';
+      /** One human line. */
+      summary: string;
+    }
+  | {
+      status: 'failed';
+      /** The step that failed. */
+      step: NexusAccountSetupStep;
+      /** Stable error code (a {@link NexusAccountErrorCode} when the flow raised one). */
+      code: string;
+      /** What went wrong. */
+      message: string;
+      /** The remedy. */
+      fix: string;
+      /** One human line naming the step and the remedy. */
+      summary: string;
+    };
+
 /** Result of `cleo login nexus` (never carries the token). */
 export interface NexusLoginResult {
   /** API origin the session belongs to. */
@@ -199,6 +270,8 @@ export interface NexusLoginResult {
   device?: NexusLoginDevice;
   /** Scopes of the stored device credential; present only with device credentials. */
   scopes?: string[];
+  /** The account key setup run right after enrolment (T13100); present only with device credentials. */
+  account?: NexusAccountSetup;
 }
 
 /** Result of `cleo logout nexus`. */

package/src/nexus-cloud.ts

@@ -167,8 +167,15 @@ const projectFields = {
 export const nexusCloudProjectListItemSchema = z.object({
   ...projectFields,
   role: z.string(),
+  /**
+   * The project name sealed with the project data key (`Project.encryptedName`), base64;
+   * only a holder of the account key can open it (T13102).
+   */
+  encryptedName: z.string().nullable().optional(),
   streamId: z.string().optional(),
   headSeq: z.number().int().nonnegative().nullable().optional(),
+  /** The stream's head snapshot; null when nothing was ever pushed (T13102: restorable or not). */
+  headCheckpointId: z.string().nullable().optional(),
   openConflicts: z.number().int().nonnegative().optional(),
   replicas: z.array(nexusCloudReplicaSchema).default([]),
   devices: nexusCloudDeviceCountsSchema.optional(),

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/project-context.ts

@@ -126,10 +126,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/resource-governor.ts

@@ -139,6 +139,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. */

package/src/task.ts

@@ -23,6 +23,7 @@
 
 import type { AcceptanceGate, AcceptanceGateResult } from './acceptance-gate.js';
 import type { AcRow } from './data-accessor.js';
+import type { HeavyToolResourcePlan } from './resource-governor.js';
 import type { TaskStatus } from './status-registry.js';
 
 export type { TaskStatus };
@@ -365,6 +366,13 @@ export type EvidenceAtom =
       treeHash?: string;
       /** `true` when the result was served from the tool cache (no spawn). */
       cacheHit?: boolean;
+      /**
+       * The heap, worker count and workspace concurrency a memory-bound tool
+       * (`test`, `build`, `typecheck`, `lint`) was spawned with, and why
+       * (T13122, T13123) — including any inherited `NODE_OPTIONS` heap or
+       * worker count that was clamped to the budget. Absent for other tools.
+       */
+      resources?: HeavyToolResourcePlan;
     }
   | { kind: 'url'; url: string }
   | { kind: 'note'; note: string }