@cleocode/contracts 2026.9.15 → 2026.9.17

package/src/agent-registry.ts

@@ -35,8 +35,18 @@ export interface AgentCredential {
   agentId: string;
   /** Human-readable display name. */
   displayName: string;
-  /** API key for authentication (`sk_live_*`). Stored encrypted at rest. */
+  /**
+   * API key for authentication (`sk_live_*`). Stored encrypted at rest (global
+   * KDF, T12352). When {@link AgentCredential.requiresReauth} is true this is
+   * NOT the real key — re-register it.
+   */
   apiKey: string;
+  /**
+   * True when the stored key is not recoverable (written before T12352, which
+   * stored a derived HMAC and discarded the key, or encrypted on another
+   * device). Re-register with `cleo agent register --id <id> --api-key <key>`.
+   */
+  requiresReauth?: boolean;
   /** Base URL of the messaging API (default: api.signaldock.io). */
   apiBaseUrl: string;
   /** Agent classification from the registry (e.g. 'code_dev', 'orchestrator'). */

package/src/code-symbol.ts

@@ -87,7 +87,7 @@ export const PARSER_WORKER_HEAP_MIN_MB = 8;
 export const PARSER_WORKER_HEAP_MAX_MB = 4_096;
 
 /** Default V8 old-space per parse worker, in MiB. */
-export const PARSER_WORKER_HEAP_DEFAULT_MB = 128;
+export const PARSER_WORKER_HEAP_DEFAULT_MB = 512;
 
 /** Bounds for one native parser invocation; cancellation is cooperative in-process. */
 export interface ParserExecutionLimits {
@@ -111,6 +111,18 @@ export interface ParserProcessHandle {
   nativeMemory: 'unverified';
   /** Kill owned execution and wait until it has exited. */
   stop(): Promise<void>;
+  /**
+   * The tail of the child's own standard error, bounded in size.
+   *
+   * The stream was drained and discarded so a full pipe could not block the
+   * child. Draining is right; discarding is not — it threw away the only
+   * account of why a worker died, leaving the parent to report the broken pipe
+   * it noticed afterwards. Retaining a bounded tail keeps the pipe moving and
+   * keeps the cause (T12313).
+   *
+   * @returns Captured stderr, newest content last; empty when the child said nothing.
+   */
+  stderrTail(): string;
 }
 
 /** Dependency-inverted access to the existing runtime process containment service. */

package/src/config.ts

@@ -751,6 +751,43 @@ export interface LeadRollupConfig {
   mode?: LeadRollupMode;
 }
 
+/**
+ * Inline refresh policy for code-graph queries (T12316).
+ *
+ * Before answering, a graph query checks how far the published index lags the
+ * working tree. When only a few files are stale it refreshes the index inline
+ * (incrementally) and discloses that it did; above these bounds it answers
+ * from the stale index with a warning instead of blocking.
+ */
+export interface NexusAutoRefreshConfig {
+  /**
+   * Whether queries may refresh the index inline.
+   *
+   * @defaultValue true
+   */
+  enabled?: boolean;
+  /**
+   * Most stale files a query refreshes inline.
+   *
+   * @defaultValue 25
+   */
+  maxFiles?: number;
+  /**
+   * Wall-clock budget in milliseconds. A refresh whose recorded-cost estimate
+   * exceeds it is not started; a started one is cancelled at the budget and
+   * leaves the previous graph intact.
+   *
+   * @defaultValue 60000
+   */
+  budgetMs?: number;
+}
+
+/** Code-graph (`cleo nexus`) configuration. */
+export interface NexusConfig {
+  /** Inline refresh of a slightly stale index before graph queries answer. */
+  autoRefresh?: NexusAutoRefreshConfig;
+}
+
 /**
  * Daemon lifecycle configuration.
  *
@@ -930,6 +967,13 @@ export interface CleoConfig {
    * @saga T10377
    */
   leadRollup?: LeadRollupConfig;
+  /**
+   * Code-graph behaviour — inline refresh bounds for stale-index queries.
+   *
+   * @defaultValue undefined (auto-refresh enabled, 25 files, 60 s)
+   * @task T12316
+   */
+  nexus?: NexusConfig;
   /**
    * Daemon lifecycle settings.
    *

package/src/credential-transfer.ts

@@ -0,0 +1,112 @@
+/**
+ * Credential transfer contracts — moving stored secrets between devices
+ * without moving the device key.
+ *
+ * CLEO encrypts stored credentials under a key derived from the local
+ * `machine-key`. That key never leaves the device (it is excluded from every
+ * backup bundle, encrypted or not). A credential therefore crosses devices in
+ * one of two ways:
+ *
+ * - **Sealed** — an encrypted backup carries the credentials re-sealed under a
+ *   key derived from the user's passphrase; the importing device unseals them
+ *   and re-encrypts each one under ITS OWN machine-key.
+ * - **Re-entered** — an unencrypted backup carries no usable credential
+ *   material; the import lists every credential to re-enter, each with the
+ *   exact command that re-enters it.
+ *
+ * @task T12326
+ * @module credential-transfer
+ */
+
+/**
+ * The store a credential lives in.
+ *
+ * - `project-agent` — `tasks_agent_credentials.api_key_encrypted` in the
+ *   project `cleo.db` (project KDF).
+ * - `service-connection` — `service_connections.credentials_enc` in the global
+ *   `cleo.db` (global KDF, id `service:<provider>:<label>`).
+ * - `llm-pool` — an entry in `<cleoHome>/llm-credentials.json`.
+ * - `agent-registry` — `agent_registry_agents.api_key_encrypted` in the global
+ *   `cleo.db` (global KDF, id `agent:<agentId>`, `gk1:` prefix — T12352).
+ *
+ * @task T12326
+ * @task T12352
+ */
+export type CredentialStoreKind =
+  | 'project-agent'
+  | 'service-connection'
+  | 'llm-pool'
+  | 'agent-registry';
+
+/**
+ * A credential identified WITHOUT its value — safe to print, log, or write
+ * into a bundle manifest.
+ *
+ * @task T12326
+ */
+export interface CredentialDescriptor {
+  /** Which store holds the credential. */
+  readonly store: CredentialStoreKind;
+  /**
+   * Stable identity within the store: the agent id (`project-agent`,
+   * `agent-registry`),
+   * `<provider>:<label>` (`service-connection`, `llm-pool`).
+   */
+  readonly id: string;
+  /** Human-readable description of the credential. */
+  readonly label: string;
+}
+
+/**
+ * A credential the target device must re-enter, with the one command that
+ * re-enters it.
+ *
+ * @task T12326
+ */
+export interface CredentialReentry extends CredentialDescriptor {
+  /** Why the credential could not be carried over. */
+  readonly reason: string;
+  /** The exact CLI command that re-enters this credential (secret shown as a placeholder). */
+  readonly reentryCommand: string;
+}
+
+/**
+ * Outcome of sealing the local credentials under a passphrase.
+ *
+ * @task T12326
+ */
+export interface SealCredentialsResult {
+  /** Sealed payload bytes (passphrase-encrypted). Never contains machine-key material. */
+  readonly sealed: Uint8Array;
+  /** Credentials carried in the sealed payload. */
+  readonly sealedCredentials: readonly CredentialDescriptor[];
+  /** Credentials that could not be decrypted locally and must be re-entered after restore. */
+  readonly reentry: readonly CredentialReentry[];
+}
+
+/**
+ * Outcome of unsealing a payload into the local stores.
+ *
+ * @task T12326
+ */
+export interface UnsealCredentialsResult {
+  /** Credentials re-encrypted under the local machine-key and written. */
+  readonly restored: readonly CredentialDescriptor[];
+  /** Credentials the operator must re-enter, each with its command. */
+  readonly reentry: readonly CredentialReentry[];
+}
+
+/**
+ * Outcome of migrating project credentials from the legacy path-bound KDF to
+ * the project-identity KDF.
+ *
+ * @task T12326
+ */
+export interface ProjectCredentialMigrationResult {
+  /** Credentials re-encrypted from the legacy path KDF to the project-id KDF. */
+  readonly migrated: readonly CredentialDescriptor[];
+  /** Credentials already under the project-id KDF (untouched). */
+  readonly current: readonly CredentialDescriptor[];
+  /** Credentials no candidate key could decrypt — ciphertext left untouched. */
+  readonly reentry: readonly CredentialReentry[];
+}

package/src/dispatch/operations-registry.ts

@@ -6965,7 +6965,12 @@ export const OPERATIONS: OperationDef[] = [
         required: false,
         description: 'JS regex matched against project_path',
       },
-      { name: 'includeTemp', type: 'boolean', required: false, description: 'Match .temp/ paths' },
+      {
+        name: 'includeTemp',
+        type: 'boolean',
+        required: false,
+        description: 'Match .temp/ or OS temp-directory paths',
+      },
       {
         name: 'includeTests',
         type: 'boolean',
@@ -7000,7 +7005,8 @@ export const OPERATIONS: OperationDef[] = [
         name: 'vacuum',
         type: 'boolean',
         required: false,
-        description: 'After delete, run sqlite VACUUM on nexus.db to reclaim space (T9117)',
+        description:
+          'After delete, VACUUM the global registry store (<cleoHome>/cleo.db) to reclaim space (T9117 · T12324)',
       },
     ],
   },

package/src/doctor.ts

@@ -1063,3 +1063,118 @@ export interface LegacyBackupScanResult {
    */
   errors: Array<{ path: string; error: string }>;
 }
+
+// ============================================================================
+// Superseded-store reconcile — `cleo doctor superseded-store --reconcile` (T12319)
+// ============================================================================
+
+/**
+ * Per-table row accounting for one legacy source table reconciled into the
+ * live project `cleo.db`.
+ *
+ * `missingInLive` counts SOURCE rows whose primary key is absent from the live
+ * table — the rows a reconcile must still copy. It is `null` only when the key
+ * cannot be compared (no shared primary key); such a table is judged by counts.
+ *
+ * @task T12319
+ */
+export interface SupersededStoreTableCount {
+  /** Logical legacy source (`tasks`, `brain (project)`, `conduit`). */
+  sourceDb: string;
+  /** Table name in the legacy file. */
+  sourceTable: string;
+  /** Consolidated table in `cleo.db` the rows land in. */
+  targetTable: string;
+  /** Rows in the legacy table. */
+  sourceRows: number;
+  /** Rows in the live table. */
+  liveRows: number;
+  /** Source rows whose key is absent from the live table, or `null` if not comparable. */
+  missingInLive: number | null;
+}
+
+/**
+ * A legacy row set an additive reconcile did NOT copy (T12355). Every one is
+ * listed; none is silently dropped.
+ *
+ * - `live-authoritative` — the table's runtime home is part of the task graph
+ *   the project has been editing on the consolidated store; a legacy row
+ *   missing there may have been deleted or rewritten since, so copying it
+ *   could resurrect or contradict live state.
+ * - `collides-with-live` — inserting the row would violate a live key or
+ *   constraint (e.g. a `(task_id, ordinal)` slot a newer criterion now holds),
+ *   i.e. it could only land by overwriting live data.
+ *
+ * @task T12355
+ */
+export interface SupersededStoreConflict {
+  /** Logical legacy source. */
+  sourceDb: string;
+  /** Table in the legacy file. */
+  sourceTable: string;
+  /** Table the runtime reads it from. */
+  targetTable: string;
+  /** Legacy rows left uncopied. */
+  rows: number;
+  /** Why they were left. */
+  reason: 'live-authoritative' | 'collides-with-live';
+}
+
+/**
+ * Outcome of `cleo doctor superseded-store --reconcile`.
+ *
+ * - `nothing-to-reconcile` — every legacy row is already present; no write.
+ * - `planned` — dry-run; `before` shows what an apply would copy.
+ * - `reconciled` — rows copied and re-verified; `after` proves zero missing.
+ * - `refused` — the post-copy verification found a mismatch; every row this
+ *   run inserted was reverted (see `rolledBack`) and the command exits non-zero.
+ *
+ * @task T12319
+ */
+export type SupersededStoreReconcileOutcome =
+  | 'nothing-to-reconcile'
+  | 'planned'
+  | 'reconciled'
+  | 'refused';
+
+/**
+ * Receipt of a superseded-store reconcile. Written verbatim to
+ * `<staging>/reconcile-receipt.json` for an apply.
+ *
+ * @task T12319
+ */
+export interface SupersededStoreReconcileResult {
+  /** Final outcome; `refused` is the only non-zero exit. */
+  outcome: SupersededStoreReconcileOutcome;
+  /**
+   * `full` — every legacy row must end up present (stranded projects).
+   * `additive` — for a project already running on the consolidated store:
+   * copy only rows whose keys are absent from live history tables, never
+   * touch the live task graph, and list everything left in `conflicts`.
+   */
+  mode: 'full' | 'additive';
+  /** Legacy rows deliberately left uncopied (additive mode); empty in full mode. */
+  conflicts: SupersededStoreConflict[];
+  /** `true` when nothing was written. */
+  dryRun: boolean;
+  /** Absolute project root. */
+  projectRoot: string;
+  /** Absolute path of the live project `cleo.db`. */
+  liveStorePath: string;
+  /** Legacy files read (never modified, moved or deleted). */
+  sourcePaths: string[];
+  /** Per-table accounting before any write. */
+  before: SupersededStoreTableCount[];
+  /** Per-table accounting after the copy; empty unless a copy ran. */
+  after: SupersededStoreTableCount[];
+  /** Rows inserted into `cleo.db` by this run (0 for dry-run / no-op). */
+  rowsCopied: number;
+  /** Rows reverted after a refused verification (0 otherwise). */
+  rolledBack: number;
+  /** Staging directory holding the journal, source backups and receipt, or `null`. */
+  stagingDir: string | null;
+  /** Absolute path of the written receipt, or `null` when none was written. */
+  receiptPath: string | null;
+  /** Human-readable explanation, suitable for printing verbatim. */
+  reason: string;
+}

package/src/errors.ts

@@ -543,6 +543,11 @@ export interface ChangesetYamlInvalidDetails {
   snippet?: string;
   /** Underlying parser message, propagated verbatim for diagnostics. */
   parserMessage: string;
+  /**
+   * Remediation naming the fix when the failure is a value starting with a
+   * YAML-reserved character, e.g. wrap it in double quotes (T12351).
+   */
+  hint?: string;
 }
 
 /**
@@ -588,7 +593,8 @@ export class ChangesetYamlInvalidError extends Error {
   constructor(details: ChangesetYamlInvalidDetails) {
     const linePart = details.line !== null ? `:${details.line}` : '';
     super(
-      `E_CHANGESET_YAML_INVALID: ${details.file}${linePart} invalid YAML frontmatter: ${details.parserMessage}`,
+      `E_CHANGESET_YAML_INVALID: ${details.file}${linePart} invalid YAML frontmatter: ${details.parserMessage}` +
+        (details.hint !== undefined ? `\n  hint: ${details.hint}` : ''),
     );
     this.name = 'ChangesetYamlInvalidError';
     this.details = details;

package/src/graph.ts

@@ -658,8 +658,19 @@ export interface GraphIndexAssessment {
   sourceRoots?: GraphSourceRootAssessment;
   /** Immutable publication identity allocated before extraction; absent on historical indexes. */
   generation?: string;
-  /** Unmodeled AST scopes remain explicit limitations instead of fabricated declarations. */
+  /**
+   * Unmodeled AST scopes remain explicit limitations instead of fabricated declarations.
+   * Absent on a summary read: the list is stored beside the assessment (T12348)
+   * and loaded only on request; {@link GraphIndexAssessment.referenceCount} still
+   * reports how many there are.
+   */
   references?: GraphIndexReferenceReport[];
+  /**
+   * Number of retained references, recorded whenever the list is stored
+   * separately from this summary (T12348). Absent on historical indexes, whose
+   * `references` are inline.
+   */
+  referenceCount?: number;
   /** Explicit nested repository/worktree scope retained for subsequent rebuilds. */
   includedRepositories?: string[];
   /** Canonical root whose relative file paths this graph describes. */
@@ -682,6 +693,116 @@ export interface GraphPublicationRows {
   nodes: NexusNodeInsertRow[];
   /** Complete replacement relationship generation. */
   relations: NexusRelationInsertRow[];
+  /**
+   * Per-file extraction memo changes committed in the same transaction as the rows.
+   * Absent when the producer does not maintain a parse cache.
+   */
+  parseCache?: GraphParseCacheUpdate;
+}
+
+/**
+ * One file's memoized extraction output, valid only for the exact bytes and extractor build.
+ *
+ * Extraction is a pure function of `(path, content, extractor build, publication generation)`;
+ * the generation token embedded in anonymous identities is rewritten on reuse, so a reused
+ * entry yields exactly what re-parsing the same bytes would.
+ */
+export interface GraphParseCacheEntry {
+  /** Path relative to the assessed source root. */
+  path: string;
+  /** SHA-256 of the bytes that produced this extraction. */
+  contentHash: string;
+  /** Fingerprint of the extractor build (code + grammars) that produced it. */
+  fingerprint: string;
+  /** Publication generation embedded in the stored payload's anonymous identities. */
+  generation: string;
+  /** Compressed serialized extraction; opaque to every owner except the producing pipeline. */
+  payload: Uint8Array;
+}
+
+/** Parse-cache mutation applied atomically with a graph publication. */
+export interface GraphParseCacheUpdate {
+  /** Extractor fingerprint every retained and written entry must carry. */
+  fingerprint: string;
+  /** Delete every existing entry before applying `upserts` (full rebuilds). */
+  reset: boolean;
+  /** Entries for files parsed during this run. */
+  upserts: GraphParseCacheEntry[];
+  /** Paths whose entries no longer describe a current, successfully parsed file. */
+  deletePaths: string[];
+}
+
+/** Why and how an index run chose between reusing prior extraction and parsing everything. */
+export interface GraphIndexRunSummary {
+  /**
+   * `incremental` parsed only files without a reusable extraction; `full` parsed every file;
+   * `unchanged` found no source difference and published nothing.
+   */
+  mode: 'incremental' | 'full' | 'unchanged';
+  /** Human-readable reason for the mode, including every full-rebuild fallback. */
+  reason: string;
+  /** Previously indexed files whose content hash differs. */
+  changedFiles: number;
+  /** Files absent from the previous generation. */
+  addedFiles: number;
+  /** Previously indexed files no longer present. */
+  deletedFiles: number;
+  /** Files handed to the parser this run. */
+  parsedFiles: number;
+  /** Files whose extraction was reused from the parse cache instead of re-parsed. */
+  reusedFiles: number;
+  /**
+   * Files whose imports, calls, accesses and heritage were re-resolved. Resolution always runs
+   * over the complete merged symbol table, so this equals every extracted file; dependents of
+   * changed files are therefore never left pointing at stale targets.
+   */
+  resolvedFiles: number;
+  /** Wall-clock milliseconds per pipeline phase, for cost disclosure. */
+  phaseMs: Record<string, number>;
+}
+
+/**
+ * Freshness of a published code-graph index relative to the working tree.
+ *
+ * Computed by metadata comparison (mtime + size) with a content-hash fallback on mismatch, so
+ * a touched-but-identical file is not reported stale.
+ */
+export interface GraphIndexFreshness {
+  /** Whether a published index exists at all. */
+  indexed: boolean;
+  /** `fresh` when no indexed file differs from disk; `stale` otherwise; `unknown` if unassessed. */
+  status: 'fresh' | 'stale' | 'unknown';
+  /** Assessment timestamp of the published generation. */
+  lastIndexedAt: string | 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[];
+  /** 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. */
+  symbolFile?: string;
+  /** Command that refreshes the index. */
+  refreshCommand: string;
+  /** Rough cost of that refresh, for the caller to decide whether to wait for it. */
+  refreshEstimate: string;
+  /** Milliseconds spent assessing freshness. */
+  checkMs: number;
+  /** Diagnostic reason when `status` is `unknown`. */
+  reason?: string;
+  /** Present when the query attempted to refresh the index inline before answering. */
+  autoRefresh?: {
+    /** Whether the inline refresh published a new generation. */
+    refreshed: boolean;
+    /** Stale files at the time the refresh was attempted. */
+    staleFiles: number;
+    /** Milliseconds the refresh took (or ran before it was abandoned). */
+    durationMs: number;
+    /** Why the refresh ran, was skipped, or failed. */
+    reason: string;
+  };
 }
 
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -291,6 +291,8 @@ export type {
   LoggingConfig,
   LogLevel,
   MemoryBridgeMode,
+  NexusAutoRefreshConfig,
+  NexusConfig,
   OutputConfig,
   OutputFormat,
   ProviderConfig,
@@ -307,6 +309,15 @@ export type {
   SystemBinding,
 } from './config.js';
 export type { AdapterContextMonitorProvider } from './context-monitor.js';
+// === Credential Transfer Types (T12326 — portable credentials) ===
+export type {
+  CredentialDescriptor,
+  CredentialReentry,
+  CredentialStoreKind,
+  ProjectCredentialMigrationResult,
+  SealCredentialsResult,
+  UnsealCredentialsResult,
+} from './credential-transfer.js';
 // === Claude Code credential parsing (T9307 — pure helper, no core imports) ===
 export type {
   ClaudeCodeOAuthBlock,
@@ -494,6 +505,10 @@ export type {
   SagaAuditResult,
   SagaAuditViolation,
   SagaAuditViolationKind,
+  SupersededStoreConflict,
+  SupersededStoreReconcileOutcome,
+  SupersededStoreReconcileResult,
+  SupersededStoreTableCount,
   WorktreeAnomaly,
   WorktreeAnomalyKind,
 } from './doctor.js';
@@ -701,9 +716,13 @@ export type {
   GraphEdgeConfidenceLabel,
   GraphIndexAssessment,
   GraphIndexFileReport,
+  GraphIndexFreshness,
   GraphIndexReferenceReport,
+  GraphIndexRunSummary,
   GraphNode,
   GraphNodeKind,
+  GraphParseCacheEntry,
+  GraphParseCacheUpdate,
   GraphPublicationRows,
   GraphRelation,
   GraphRelationType,
@@ -1478,9 +1497,13 @@ export type {
   NexusPermissionLevel,
   NexusPermissionSetParams,
   NexusPermissionSetResult,
+  NexusProjectCheckout,
   NexusProjectRecord,
   NexusProjectStats,
   NexusProjectsCleanParams,
+  NexusProjectsCleanReason,
+  NexusProjectsCleanReceipt,
+  NexusProjectsCleanRemoval,
   NexusProjectsCleanResult,
   NexusProjectsListParams,
   NexusProjectsListResult,
@@ -1498,6 +1521,7 @@ export type {
   NexusRefreshBridgeResult,
   NexusRegisterParams,
   NexusRegisterResult,
+  NexusRegistryClassification,
   NexusResolveParams,
   NexusResolveResult,
   NexusRouteMapParams,
@@ -1950,6 +1974,32 @@ export type {
   PlaybookRun,
   PlaybookRunStatus,
 } from './playbook.js';
+// === Portable Bundle (manifest v2) Types (T12318 — lossless machine migration) ===
+export type {
+  PortableBundleManifest,
+  PortableBundleScope,
+  PortableDatabaseEntry,
+  PortableDatabaseRole,
+  PortableExclusion,
+  PortableExportResult,
+  PortableFileEntry,
+  PortableGlobalSection,
+  PortableImportResult,
+  PortableImportSectionResult,
+  PortableKeyCounts,
+  PortableLegacyEvidence,
+  PortablePathFinding,
+  PortableProjectSection,
+  PortableReentryItem,
+  PortableRelocationReport,
+  PortableSealedCredentials,
+  PortableSectionBase,
+  PortableSkippedProject,
+  PortableSkipReason,
+  PortableSymlinkEntry,
+  PortableTableComparison,
+  PortableUnmigratedLegacyReport,
+} from './portable-bundle.js';
 // === PostgresDataAccessor Contracts — cloud-sync scaffold (T9062) ===
 export type {
   CreatePostgresDataAccessorFn,