@cleocode/contracts 2026.10.21 → 2026.10.22

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

@@ -224,6 +224,9 @@ type _ObserveBrainResultShape = {
   createdAt: string;
   typeSource?: 'caller' | 'keyword' | 'system-one';
   typeConfidence?: number;
+  stored?: false;
+  gateAction?: 'merged' | 'pending' | 'rejected';
+  gateReason?: string;
 };
 
 type _AssertObserveResultPinned = AssertEquals1<

package/src/boundary.ts

@@ -300,22 +300,6 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     rationale:
       'Verified-dead code: 531 LOC Rust crate referenced ONLY by packages/core/src/llm/rust/__tests__/. Production transports (chat-completions/gemini/openai) import StreamingThinkScrubber from the TS think-scrubber.js path. CLEO_USE_RUST gate is never set in any workflow. Scheduled for deletion in T10205; see ADR-078 implementation tasks.',
   },
-  {
-    module: 'cleo-conduit-core',
-    intent: 'data-manifest',
-    rustCore: 'crates/cleo-conduit-core',
-    canonicalHome: 'cleocode',
-    perfBudget: {
-      latency_p50_ms: 10,
-    },
-    safetyBudget: {
-      panic_unwind: 'forbidden',
-      root_escape: 'forbidden',
-    },
-    amendments: [],
-    rationale:
-      'Conduit serde-types crate (681 LOC) — renamed from conduit-core to cleo-conduit-core (T10185, saga T10180) because conduit-core is squatted on crates.io. Stable contract surface consumed by cant-core, signaldock-protocol, signaldock-core, integration-tests, AND external /mnt/projects/signaldock-core + /mnt/projects/signaldock/backend via git deps. Mirrors @cleocode/contracts/conduit.ts. Forced KEEP+publish=true: deleting breaks production, and signaldock-protocol publish requires it.',
-  },
   {
     module: 'cleo-supervisor',
     intent: 'scaffold-pending-consumer',
@@ -349,7 +333,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'Internal Rust test harness over lafs-core/cleo-conduit-core/cant-core. publish=false intentional — test code never ships.',
+      'Internal Rust test harness over lafs-core/cant-core (cleo-conduit-core removed in T13954). publish=false intentional — test code never ships.',
   },
   {
     module: 'lafs-core',
@@ -367,7 +351,7 @@ export const BOUNDARY_REGISTRY: readonly BoundaryEntry[] = [
     },
     amendments: [],
     rationale:
-      'LAFS envelope serialization core (1,432 LOC) consumed by cleo-conduit-core, signaldock-protocol, lafs-napi, integration-tests. Mirrors @cleocode/lafs/src/envelope.ts. Flip publish=true to expose canonical envelope spec as a Rust library.',
+      'LAFS envelope serialization core (1,432 LOC) consumed by signaldock-protocol, lafs-napi, integration-tests. Mirrors @cleocode/lafs/src/envelope.ts. Flip publish=true to expose canonical envelope spec as a Rust library.',
   },
   {
     module: 'lafs-napi',

package/src/config.ts

@@ -126,6 +126,14 @@ export interface VerificationConfig {
   maxRounds: number;
   /** Gate names required for completion. */
   requiredGates: string[];
+  /**
+   * Gates required per evidence kind (T14001), overriding `requiredGates`
+   * for that kind. Defaults: research and documentation get `requiredGates`
+   * without `testsPassed`/`qaPassed`; code gets `requiredGates`. A task whose
+   * implemented evidence or change set touches any non-document path owes
+   * the code gates whatever its kind.
+   */
+  requiredGatesByKind?: Partial<Record<'code' | 'documentation' | 'research', string[]>>;
 }
 
 /** Lifecycle enforcement mode. */
@@ -159,6 +167,18 @@ export interface LifecycleConfig {
    * @defaultValue 'critical'
    */
   depsRequiredAt?: DepsRequiredAt;
+  /**
+   * Parent-epic stage gate, separate from {@link LifecycleConfig.mode}. When
+   * `strict`, a child cannot complete while its parent epic sits in a
+   * planning stage, an epic cannot advance while children sit at its stage,
+   * and a child cannot pass its epic's stage; `advisory` only warns. Unset
+   * means `off`: those three checks are opt-in, because together they can
+   * strand an epic's children (T13969). Evidence strictness stays on `mode`.
+   *
+   * @task T13970
+   * @defaultValue 'off'
+   */
+  stageGate?: LifecycleEnforcementMode;
 }
 
 /** Sharing mode: whether .cleo/ files are committed to the project git repo. */
@@ -777,8 +797,10 @@ export interface NexusAutoRefreshConfig {
    */
   enabled?: boolean;
   /**
-   * Most stale files a query refreshes inline.
+   * Retired (T14014) and ignored: a query refreshes inline whenever the
+   * size-scaled cost estimate fits `budgetMs`.
    *
+   * @deprecated The cost estimate against `budgetMs` decides.
    * @defaultValue 25
    */
   maxFiles?: number;
@@ -792,10 +814,56 @@ export interface NexusAutoRefreshConfig {
   budgetMs?: number;
 }
 
+/**
+ * When a graph answer from a stale index is refused (T14008).
+ *
+ * @task T14008
+ */
+export interface NexusFreshnessConfig {
+  /**
+   * Most commits the index may trail the checked-out HEAD before graph
+   * queries fail with `E_NEXUS_INDEX_STALE` (`--allow-stale` or
+   * `CLEO_NEXUS_ALLOW_STALE=1` accepts the stale answer).
+   *
+   * @defaultValue 50
+   */
+  maxCommitsBehind?: number;
+}
+
+/**
+ * Background reindex after a merge into the base branch (T14010). Started by
+ * the CLEO `post-merge` hook only when the `cleo.nexusReindexOnMerge` git
+ * marker is set (`cleo nexus reindex-on-merge --enable` sets both); runs at
+ * the lowest admission priority, one at a time per project, and records its
+ * outcome for `cleo nexus status`.
+ *
+ * @task T14010
+ */
+export interface NexusReindexOnMergeConfig {
+  /**
+   * Whether a merge into the base branch starts a background reindex. Off by
+   * default: a heavy analysis after every merge must be a choice.
+   *
+   * @defaultValue false
+   */
+  enabled?: boolean;
+  /**
+   * Seconds the reindex keeps trying for `cleo run` admission (never queueing,
+   * only when nothing else waits) before it is recorded as deferred.
+   *
+   * @defaultValue 300
+   */
+  timeoutSeconds?: number;
+}
+
 /** Code-graph (`cleo nexus`) configuration. */
 export interface NexusConfig {
+  /** Background reindex after a merge into the base branch (T14010). */
+  reindexOnMerge?: NexusReindexOnMergeConfig;
   /** Inline refresh of a slightly stale index before graph queries answer. */
   autoRefresh?: NexusAutoRefreshConfig;
+  /** When an answer from a stale index is refused instead of returned. */
+  freshness?: NexusFreshnessConfig;
 }
 
 /**

package/src/dispatch/operations-registry.ts

@@ -4815,6 +4815,32 @@ export const OPERATIONS: OperationDef[] = [
       },
     ],
   },
+  // T13949 — curated lessons index (D11181)
+  {
+    gateway: 'query',
+    domain: 'memory',
+    operation: 'lessons',
+    description:
+      "memory.lessons (query) — list current type='lesson' observations (one-line rule + why), newest first, superseded hidden",
+    tier: 1,
+    idempotent: true,
+    sessionRequired: false,
+    requiredParams: [],
+    params: [
+      {
+        name: 'scope',
+        type: 'string',
+        required: false,
+        description: 'Store to read: project, global (the main brain) or all (default)',
+      },
+      {
+        name: 'limit',
+        type: 'number',
+        required: false,
+        description: 'Max lessons to return (default: 50)',
+      },
+    ],
+  },
   // T1006 — long-poll stream of recent brain writes (SSE-style polling stub)
   {
     gateway: 'query',

package/src/evidence-atom-schema.ts

@@ -228,6 +228,15 @@ export const prAtomSchema = z.object({
   kind: z.literal('pr'),
   prNumber: z.number().int().positive('pr atom requires a positive integer PR number'),
   componentPrNumber: z.number().int().positive().optional(),
+  /**
+   * `pr:<owner>/<repo>#<n>` (T13912): the GitHub repository the PR number
+   * belongs to, lowercased. Validated against the evidence git root's
+   * `origin`, since PR numbers are only unique per repository.
+   */
+  repo: z
+    .string()
+    .regex(/^[a-z0-9._-]+\/[a-z0-9._-]+$/)
+    .optional(),
 });
 
 /**
@@ -246,6 +255,11 @@ export const ciAtomSchema = z.object({
   kind: z.literal('ci'),
   prNumber: z.number().int().positive('ci atom requires a positive integer PR number'),
   componentPrNumber: z.number().int().positive().optional(),
+  /** `ci:<owner>/<repo>#<n>`, as for `pr:` (T13912). */
+  repo: z
+    .string()
+    .regex(/^[a-z0-9._-]+\/[a-z0-9._-]+$/)
+    .optional(),
 });
 
 /**
@@ -803,18 +817,22 @@ export class EvidenceParseError extends Error {
  * @adr ADR-051
  */
 /**
- * `<n>` or `<component>@<integration>` (T12671), each a positive integer.
- * The integration PR is the atom's `prNumber`.
+ * `<n>` or `<component>@<integration>` (T12671), each a positive integer,
+ * optionally prefixed `<owner>/<repo>#` (T13912). The integration PR is the
+ * atom's `prNumber`.
  */
 function parsePrReference(
   payload: string,
-): { prNumber: number; componentPrNumber?: number } | null {
-  const match = /^(\d+)(?:@(\d+))?$/.exec(payload);
+): { prNumber: number; componentPrNumber?: number; repo?: string } | null {
+  const match = /^(?:([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+)#)?(\d+)(?:@(\d+))?$/.exec(payload);
   if (!match) return null;
-  const first = Number(match[1]);
-  const second = match[2] === undefined ? null : Number(match[2]);
+  const repo = match[1] === undefined ? {} : { repo: match[1].toLowerCase() };
+  const first = Number(match[2]);
+  const second = match[3] === undefined ? null : Number(match[3]);
   if (first <= 0 || (second !== null && (second <= 0 || second === first))) return null;
-  return second === null ? { prNumber: first } : { prNumber: second, componentPrNumber: first };
+  return second === null
+    ? { prNumber: first, ...repo }
+    : { prNumber: second, componentPrNumber: first, ...repo };
 }
 
 export function parseEvidenceString(raw: string): EvidenceAtom[] {
@@ -895,7 +913,7 @@ export function parseEvidenceString(raw: string): EvidenceAtom[] {
         if (!ref) {
           throw new EvidenceParseError(
             `${kind} atom requires a positive integer PR number, got "${payload}" in "${chunk}"`,
-            `Use format: ${kind}:<number> e.g. ${kind}:357, or ${kind}:<component>@<integration> e.g. ${kind}:356@357`,
+            `Use format: ${kind}:<number> e.g. ${kind}:357, ${kind}:<component>@<integration> e.g. ${kind}:356@357, or ${kind}:<owner>/<repo>#<number>`,
           );
         }
         atoms.push(kind === 'pr' ? { kind: 'pr', ...ref } : { kind: 'ci', ...ref });

package/src/exit-codes.ts

@@ -325,6 +325,31 @@ export enum ExitCode {
    * @saga T10538 (PM-Core V2 agent-trust)
    */
   CANCELLED_CHILD_NO_WAIVER = 109,
+
+  /**
+   * E_OBSERVE_NOT_STORED — `cleo memory observe` stored nothing: the
+   * extraction gate merged the text into an existing entry (a duplicate),
+   * deferred it or rejected it.
+   *
+   * `error.details.id` names the existing entry for a duplicate, so a script
+   * can treat this code as "already known" and keep that id.
+   *
+   * @codeName E_OBSERVE_NOT_STORED
+   * @task T13949
+   */
+  OBSERVE_NOT_STORED = 110,
+
+  /**
+   * E_NEXUS_INDEX_STALE — a `cleo nexus` graph answer was refused because the
+   * index trails the checked-out HEAD by more than
+   * `nexus.freshness.maxCommitsBehind`, or the queried symbol is missing from
+   * an index that is stale for this checkout. `error.fix` names the reindex command; `--allow-stale` (or
+   * `CLEO_NEXUS_ALLOW_STALE=1`) accepts the stale answer.
+   *
+   * @codeName E_NEXUS_INDEX_STALE
+   * @task T14008
+   */
+  NEXUS_INDEX_STALE = 111,
 }
 
 // ---------------------------------------------------------------------------

package/src/facade.ts

@@ -40,6 +40,8 @@ export const BRAIN_OBSERVATION_TYPES = [
   'refactor',
   'diary',
   'session-summary',
+  /** T13949: a one-line rule (title) with its why (narrative). */
+  'lesson',
 ] as const;
 
 /** Brain observation type. */

package/src/git-hooks.ts

@@ -1,8 +1,11 @@
 /** Hash-guarded Git hook installation and recovery contracts. */
 import { z } from 'zod';
 
-/** Canonical names of the three shipped Git checks. */
-export const CLEO_GIT_HOOK_NAMES = ['commit-msg', 'pre-commit', 'pre-push'] as const;
+/**
+ * Canonical names of the shipped Git hooks: three checks, and `post-merge`,
+ * which starts an opt-in background NEXUS reindex (T14010).
+ */
+export const CLEO_GIT_HOOK_NAMES = ['commit-msg', 'pre-commit', 'pre-push', 'post-merge'] as const;
 
 /** One recoverable managed Git hook change. */
 export const GitHookChangeSchema = z.object({

package/src/graph.ts

@@ -831,6 +831,12 @@ export interface GraphParseCacheUpdate {
   upserts: GraphParseCacheEntry[];
   /** Paths whose entries no longer describe a current, successfully parsed file. */
   deletePaths: string[];
+  /**
+   * When present, delete every entry whose path is not listed (T14009): a
+   * checkpointing run already stored what it parsed during the run, so it keeps
+   * exactly this generation's files instead of rewriting them.
+   */
+  retainPaths?: string[];
 }
 
 /** Why and how an index run chose between reusing prior extraction and parsing everything. */
@@ -860,6 +866,12 @@ export interface GraphIndexRunSummary {
   resolvedFiles: number;
   /** Wall-clock milliseconds per pipeline phase, for cost disclosure. */
   phaseMs: Record<string, number>;
+  /**
+   * Set when community detection was skipped because its estimate exceeded
+   * the run's remaining budget (T14016); the generation then has no
+   * communities until an unbudgeted analysis.
+   */
+  communitiesSkipped?: string;
 }
 
 /**
@@ -875,12 +887,61 @@ export interface GraphIndexFreshness {
   status: 'fresh' | 'stale' | 'unknown';
   /** Assessment timestamp of the published generation. */
   lastIndexedAt: string | null;
+  /**
+   * Revision the published generation indexed; `null` when no revision was
+   * recorded (T14007).
+   */
+  indexedRevision?: string | null;
+  /**
+   * Ref freshness is measured against: origin's default branch, else a local
+   * `main`/`master`, else `HEAD` (T14007).
+   */
+  baseRef?: string | null;
+  /** Commit {@link GraphIndexFreshness.baseRef} names. */
+  baseRevision?: string | null;
+  /**
+   * Commits on the base ref the index has not seen (`git rev-list --count
+   * indexedRevision..baseRef`); `null` when either revision is unknown here.
+   */
+  commitsBehind?: number | null;
+  /**
+   * Commits on the checked-out HEAD the index has not seen (`git rev-list
+   * --count indexedRevision..HEAD`); `null` when unknown. A stale refusal is
+   * judged on this, never on {@link GraphIndexFreshness.commitsBehind} (T14008).
+   */
+  commitsBehindHead?: number | null;
+  /**
+   * Tracked files that differ between the indexed revision and the working
+   * tree (`git diff --name-only`), counted without a walk (T14014). Reporting
+   * only: `staleFileCount` (manifest walk) stays authoritative.
+   */
+  changedFilesSinceIndex?: number | null;
+  /**
+   * Set while inline refreshes are paused after one failed or was aborted
+   * (T14014): until this instant, or the next successful analysis.
+   */
+  refreshCooldownUntil?: string;
+  /** Whole days since {@link GraphIndexFreshness.lastIndexedAt}; `null` when never indexed. */
+  ageDays?: number | null;
   /** Files recorded in the published generation's assessment. */
   fileCount: number;
   /** Modified, added and deleted source files. */
   staleFileCount: number;
   /** Up to a bounded sample of stale paths, for disclosure. */
   stalePaths: string[];
+  /**
+   * Indexed files that no longer exist on disk (a deleted file or a removed
+   * clone the index still answers from; T14021). A subset of the stale set.
+   */
+  missingFileCount?: number;
+  /** Up to a bounded sample of {@link GraphIndexFreshness.missingFileCount}'s paths. */
+  missingPaths?: string[];
+  /**
+   * Set when the published generation was analyzed under a budget that skipped
+   * community detection (T14016): it has no communities until an unbudgeted
+   * `cleo nexus analyze`. Carries the reason.
+   */
+  communitiesSkipped?: string;
   /** Whether the queried symbol's own file is stale; absent when no symbol file is known. */
   symbolFileStale?: boolean;
   /** The symbol file the `symbolFileStale` verdict describes. */
@@ -906,6 +967,37 @@ export interface GraphIndexFreshness {
   };
 }
 
+/**
+ * How current the graph behind an answer is, returned at the top level of
+ * every index-sensitive `cleo nexus` answer as `data.freshness` (T14008).
+ */
+export interface NexusAnswerFreshness {
+  /** Working-tree verdict of {@link GraphIndexFreshness.status}. */
+  status: GraphIndexFreshness['status'];
+  /** Revision the index was built from. */
+  indexedRevision: string | null;
+  /** Ref the index is measured against. */
+  baseRef: string | null;
+  /** Commits on the base ref the index has not seen (reported only). */
+  commitsBehind: number | null;
+  /** Commits on the checked-out HEAD the index has not seen; the stale refusal is judged on this. */
+  commitsBehindHead: number | null;
+  /** Tracked files changed since the indexed revision (walk-free, reporting only; T14014). */
+  changedFilesSinceIndex: number | null;
+  /** Inline refreshes are paused until this instant after one failed (T14014). */
+  refreshCooldownUntil: string | null;
+  /** Whole days since the index was built. */
+  ageDays: number | null;
+  /** When the index was built. */
+  lastIndexedAt: string | null;
+  /** Indexed files that no longer exist on disk; `null` when unassessed (T14021). */
+  missingFileCount: number | null;
+  /** A bounded sample of those paths. */
+  missingPaths: string[];
+  /** Why the generation has no communities (a budgeted run skipped them); `null` otherwise (T14016). */
+  communitiesSkipped: string | null;
+}
+
 // ---------------------------------------------------------------------------
 // Impact analysis result
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -301,6 +301,8 @@ export type {
   MemoryBridgeMode,
   NexusAutoRefreshConfig,
   NexusConfig,
+  NexusFreshnessConfig,
+  NexusReindexOnMergeConfig,
   OutputConfig,
   OutputFormat,
   ProviderConfig,
@@ -825,6 +827,7 @@ export type {
   ImpactResult,
   InferredProvenance,
   KnowledgeGraph,
+  NexusAnswerFreshness,
   NexusNodeInsertRow,
   NexusRelationInsertRow,
   ProcessNode,
@@ -946,6 +949,8 @@ export {
 } from './lafs.js';
 // === ct-lean levels (T13663 / Epic T13418) ===
 export type {
+  BriefMapFile,
+  BriefMapReport,
   LeanConfig,
   LeanDebtItem,
   LeanDebtReport,
@@ -1647,6 +1652,7 @@ export type {
   NexusProjectRecord,
   NexusProjectStats,
   NexusProjectsCleanIdMismatch,
+  NexusProjectsCleanOtherHost,
   NexusProjectsCleanParams,
   NexusProjectsCleanReason,
   NexusProjectsCleanReceipt,
@@ -2360,6 +2366,8 @@ export type {
   HeavyHeapSource,
   HeavyLeverChange,
   HeavyToolResourcePlan,
+  MemoryConsumer,
+  MemoryConsumers,
   MemoryPressureReading,
   ResourceClass,
   ResourceDeferral,

package/src/lean.ts

@@ -33,6 +33,35 @@ export interface LeanConfig {
    * @defaultValue 'full'
    */
   level?: LeanLevel;
+  /**
+   * Add the brief codebase map (`cleo map --brief`) to `cleo briefing`, so
+   * "reuse first" costs no search (T13666).
+   *
+   * @defaultValue false
+   */
+  map?: boolean;
+}
+
+/** One file's exported names, the input to the brief map (T13666). */
+export interface BriefMapFile {
+  /** Repo-relative path. */
+  readonly file: string;
+  /** Exported top-level names, in source order. */
+  readonly names: readonly string[];
+}
+
+/** `cleo map --brief`: what already exists, one line per folder, within a budget. */
+export interface BriefMapReport {
+  /** Where the names came from: the parsed nexus graph, or a git-tracked regex walk. */
+  readonly source: 'nexus' | 'git-walk';
+  /** The rendered map (empty when nothing was found). */
+  readonly text: string;
+  /** Folders listed. */
+  readonly folders: number;
+  /** Folders left out to stay within the budget. */
+  readonly skipped: number;
+  /** The character budget used. */
+  readonly budget: number;
 }
 
 /**

package/src/memory/observe.ts

@@ -164,23 +164,35 @@ export interface ObserveBrainResult {
   typeSource?: 'caller' | 'keyword' | 'system-one';
   /** T12494: confidence behind a `keyword` (flat 0.5) or `system-one` type. */
   typeConfidence?: number;
+  /**
+   * T13949: `false` when the extraction gate stored nothing (it merged into an
+   * existing entry, deferred or rejected the write). `id` is then the existing
+   * entry, or a placeholder. Absent when a row was stored.
+   */
+  stored?: false;
+  /** T13949: the gate's decision when nothing was stored. */
+  gateAction?: 'merged' | 'pending' | 'rejected';
+  /** T13949: the gate's explanation when nothing was stored. */
+  gateReason?: string;
 }
 
 // ── DocAttachmentObservationPayload ─────────────────────────────────
 
 /**
- * Structured payload stored in the `narrative` of a doc-attachment memory
- * observation emitted by `cleo docs add` (T9976).
+ * Source metadata of a document projection: the attachment, its owner, when
+ * it was added, and its slug and type.
  *
- * The observation title is `"Doc attached: <slug>"` (or
- * `"Doc attached: <attachmentId>"` when no slug is set) so
- * `cleo memory find '<slug>'` reliably surfaces the entry via FTS.
+ * Since T13985 (D11180) `cleo docs add` records the link as a `documents`
+ * graph edge and writes no "Doc attached" observation; this payload is the
+ * projection proposal's source metadata (`DocsProjectionProposal.observation`).
+ * Legacy observations written before T13985 still carry it as JSON in their
+ * `narrative`, which the auto-row filters and the quarantine match on.
  *
- * The payload is serialised as JSON and embedded in the observation
- * `narrative` field so it can be recovered by `cleo memory verify`
- * for round-trip attachment-existence checks.
+ * The name is kept deliberately (T13992): it is a published `@cleocode/contracts`
+ * type, and renaming it would break consumers for no behavioural gain.
  *
  * @task T9976
+ * @task T13992
  */
 export interface DocAttachmentObservationPayload {
   /** Slug recorded for this attachment (optional — omitted when none set). */

package/src/operations/docs.ts

@@ -642,11 +642,17 @@ export const DOCS_PROJECTION_RECEIPT_SCHEMA = z
     version: z.literal(1),
     sourceHash: z.string().regex(/^[a-f0-9]{64}$/),
     graph: z.enum(['completed', 'disabled']),
-    observationId: z.string().min(1),
+    /** Legacy receipts (before T13985): the "Doc attached" observation the projection wrote. */
+    observationId: z.string().min(1).optional(),
+    /** T13985 (D11180): the canonical `llmtxt --documents--> owner` edge was written. */
+    documents: z.literal(true).optional(),
     verifiedAt: z.string().min(1),
     actor: z.string().min(1),
   })
-  .strict();
+  .strict()
+  .refine((receipt) => receipt.observationId !== undefined || receipt.documents === true, {
+    message: 'A projection receipt records its documents edge or, for legacy jobs, its observation',
+  });
 
 /** Domain verification record; this is not a cross-database atomic repair receipt. */
 export type DocsProjectionReceipt = z.infer<typeof DOCS_PROJECTION_RECEIPT_SCHEMA>;

package/src/operations/nexus.ts

@@ -1815,7 +1815,7 @@ export interface NexusProjectsCleanParams {
   includeTemp?: boolean;
   /** Match paths containing tmp/test(s)/__tests__/fixture(s)/scratch/sandbox segments. */
   includeTests?: boolean;
-  /** Also match unhealthy rows. */
+  /** Also match rows recorded unreachable whose path no longer answers (T14011). */
   matchUnhealthy?: boolean;
   /** Also match never-indexed rows. */
   matchNeverIndexed?: boolean;
@@ -1957,6 +1957,25 @@ export interface NexusProjectsCleanResult {
    * path proves a project gone. Absent when none.
    */
   idMismatch?: NexusProjectsCleanIdMismatch[];
+  /**
+   * Matched rows that were NOT removed because the project lives on another
+   * machine (T14013): its recorded locations are all on other devices
+   * (`other-host`), or it has none and its path root does not exist here
+   * (`foreign-root`). Absent when none.
+   */
+  otherHost?: NexusProjectsCleanOtherHost[];
+}
+
+/** A registry row `nexus.projects.clean` kept because it belongs to another machine (T14013). */
+export interface NexusProjectsCleanOtherHost {
+  /** Immutable registry project ID. */
+  projectId: string;
+  /** Registered path. */
+  projectPath: string;
+  /** `other-host` (recorded on other devices only) or `foreign-root` (no record; path root absent here). */
+  host: 'other-host' | 'foreign-root';
+  /** Devices holding a recorded location (empty for `foreign-root`). */
+  devices: string[];
 }
 
 /** A registry row `nexus.projects.clean` kept because its path declares another id (T12471). */

package/src/operations/session.ts

@@ -527,6 +527,12 @@ export interface SessionBriefingShowResult {
    * when the attachment store is unavailable or no attachments exist.
    */
   docsContext?: SessionBriefingDocsContext;
+  /**
+   * Brief codebase map (`cleo map --brief`): exported names per folder.
+   * Present only when the `lean.map` config key is on (T13666). Read from the
+   * nexus graph only; an unindexed project gets `no code index; run \`cleo nexus analyze\``.
+   */
+  codebaseMap?: string;
 }
 
 // session.history (query — not in primary handler but exported for completeness)

package/src/resource-governor.ts

@@ -128,6 +128,34 @@ export interface MemoryPressureReading {
   readonly memAvailableBytes: number | null;
   /** The platform signals in one line (kernel level, swap, compressor, PSI). */
   readonly summary: string;
+  /**
+   * The host's largest memory users when the gate refused (T13914), so a wait
+   * names what took the memory, CLEO or not. Absent when not probed.
+   */
+  readonly topConsumers?: MemoryConsumers;
+}
+
+/** One process holding host memory (T13914). */
+export interface MemoryConsumer {
+  /** Process id. */
+  readonly pid: number;
+  /** Command name, as the process table shows it. */
+  readonly command: string;
+  /**
+   * Memory it holds in bytes: on macOS its footprint (`top` MEM: resident plus
+   * compressed and swapped pages, which `ps` RSS leaves out), on Linux its RSS.
+   */
+  readonly footprintBytes: number;
+}
+
+/** The largest memory users at one moment (T13914). */
+export interface MemoryConsumers {
+  /** When they were probed (epoch ms). */
+  readonly sampledAtMs: number;
+  /** Largest first; empty when the probe failed. */
+  readonly processes: readonly MemoryConsumer[];
+  /** `true` when no probe could list them (the cause is then UNKNOWN). */
+  readonly failed?: boolean;
 }
 
 /**