@cleocode/core 2026.4.11 → 2026.4.12

package/src/errors.ts

@@ -77,6 +77,23 @@ function exitCodeToLafsCode(code: ExitCode): string {
   return `E_${category}_${name}`;
 }
 
+/**
+ * Structured field-level details for constraint-violation errors.
+ * Surfaces in the LAFS envelope so agents can recover programmatically.
+ *
+ * @task T341
+ */
+export interface CleoErrorDetails {
+  /** The specific field that failed validation. */
+  field: string;
+  /** The expected value or constraint (e.g. max length, valid enum members). */
+  expected?: unknown;
+  /** The actual value that was provided. */
+  actual?: unknown;
+  /** Additional context keys. */
+  [key: string]: unknown;
+}
+
 /**
  * Structured error class for CLEO operations.
  * Carries an exit code, human-readable message, and optional fix suggestions.
@@ -87,6 +104,8 @@ export class CleoError extends Error {
   readonly code: ExitCode;
   readonly fix?: string;
   readonly alternatives?: Array<{ action: string; command: string }>;
+  /** Field-level details for constraint-violation errors. @task T341 */
+  readonly details?: CleoErrorDetails;
 
   constructor(
     code: ExitCode,
@@ -94,6 +113,7 @@ export class CleoError extends Error {
     options?: {
       fix?: string;
       alternatives?: Array<{ action: string; command: string }>;
+      details?: CleoErrorDetails;
       cause?: unknown;
     },
   ) {
@@ -102,6 +122,7 @@ export class CleoError extends Error {
     this.code = code;
     this.fix = options?.fix;
     this.alternatives = options?.alternatives;
+    this.details = options?.details;
   }
 
   /**
@@ -121,6 +142,7 @@ export class CleoError extends Error {
         name: getExitCodeName(this.code),
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { fieldDetails: this.details }),
       },
     };
   }
@@ -145,6 +167,7 @@ export class CleoError extends Error {
         recoverable: isRecoverableCode(this.code),
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { fieldDetails: this.details }),
       },
     };
   }
@@ -159,6 +182,7 @@ export class CleoError extends Error {
         message: this.message,
         ...(this.fix && { fix: this.fix }),
         ...(this.alternatives && { alternatives: this.alternatives }),
+        ...(this.details && { details: this.details }),
       },
     };
   }

package/src/hooks/handlers/__tests__/hook-automation-e2e.test.ts

@@ -59,7 +59,6 @@ function makeConfig(
     autoCapture?: boolean;
     captureWork?: boolean;
     captureFiles?: boolean;
-    captureMcp?: boolean;
     autoRefresh?: boolean;
   } = {},
 ): Awaited<ReturnType<typeof configModule.loadConfig>> {
@@ -68,7 +67,6 @@ function makeConfig(
       autoCapture: overrides.autoCapture ?? true,
       captureWork: overrides.captureWork ?? false,
       captureFiles: overrides.captureFiles ?? false,
-      captureMcp: overrides.captureMcp ?? false,
       memoryBridge: { autoRefresh: overrides.autoRefresh ?? false },
       embedding: { enabled: false, provider: 'local' },
       summarization: { enabled: false },
@@ -564,9 +562,8 @@ describe('hook automation E2E', () => {
       );
     });
 
-    it('work-capture and mcp-hooks register on same event but use different config keys', async () => {
-      // work-capture is keyed on captureWork; mcp-hooks keyed on captureMcp
-      // When both are disabled (default), neither fires
+    it('work-capture does not fire when captureWork is disabled (default)', async () => {
+      // When captureWork is disabled (default), work-capture does not fire
       await handleWorkPromptSubmit(PROJECT_ROOT, {
         timestamp: TIMESTAMP,
         gateway: 'mutate',

package/src/init.ts

@@ -11,8 +11,7 @@
  *   4. Sequence counter (SQLite schema_meta)
  *   5. Project info (.cleo/project-info.json)
  *   6. CAAMP injection into agent instruction files (AGENTS.md hub pattern)
- *   7. (removed — was MCP server installation)
- *   8. Agent definition installation (cleo-subagent)
+ *   7. Agent definition installation (cleo-subagent)
  *   9. Core skill installation via CAAMP
  *  10. NEXUS project registration
  *  11. Project type detection (--detect)

package/src/internal.ts

@@ -422,17 +422,31 @@ export {
   isCleoGitInitialized,
 } from './store/git-checkpoint.js';
 export { computeChecksum, readJson } from './store/json.js';
+export type { MigrationResult } from './store/migrate-signaldock-to-conduit.js';
+export {
+  migrateSignaldockToConduit,
+  needsSignaldockToConduitMigration,
+} from './store/migrate-signaldock-to-conduit.js';
 export { createSession, getActiveSession } from './store/session-store.js';
 export {
+  _resetGlobalSignaldockDb_TESTING_ONLY,
+  checkGlobalSignaldockDbHealth,
   checkSignaldockDbHealth,
+  ensureGlobalSignaldockDb,
   ensureSignaldockDb,
+  GLOBAL_SIGNALDOCK_DB_FILENAME,
+  GLOBAL_SIGNALDOCK_SCHEMA_VERSION,
+  getGlobalSignaldockDbPath,
+  getGlobalSignaldockNativeDb,
   getSignaldockDbPath,
   SIGNALDOCK_SCHEMA_VERSION,
 } from './store/signaldock-sqlite.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
-export type { BackupScope, GlobalBackupEntry } from './store/sqlite-backup.js';
+export type { BackupScope, GlobalBackupEntry, GlobalSaltBackupEntry } from './store/sqlite-backup.js';
 export {
+  backupGlobalSalt,
   listBrainBackups,
+  listGlobalSaltBackups,
   listGlobalSqliteBackups,
   listSqliteBackups,
   listSqliteBackupsAll,
@@ -589,6 +603,7 @@ export type {
 export {
   buildCommanderArgs,
   buildCommanderOptionString,
+  buildDispatchInputSchema,
   buildMcpInputSchema,
   camelToKebab,
   validateRequiredParamsDef,
@@ -847,6 +862,30 @@ export { createSqliteDataAccessor } from './store/sqlite-data-accessor.js';
 // Validation — doctor checks (used by cleo init tests)
 export { checkRootGitignore } from './validation/doctor/checks.js';
 
+// ---------------------------------------------------------------------------
+// T310 startup sequence exports (required by cli/index.ts T360 wire-up)
+// ---------------------------------------------------------------------------
+
+// Conduit DB lifecycle — ensureConduitDb is called at every CLI startup (step 3)
+export type { ProjectAgentRef } from './store/conduit-sqlite.js';
+export {
+  CONDUIT_DB_FILENAME,
+  CONDUIT_SCHEMA_VERSION,
+  checkConduitDbHealth,
+  ensureConduitDb,
+  getConduitDbPath,
+  getConduitNativeDb,
+} from './store/conduit-sqlite.js';
+
+// Global-salt lifecycle — validateGlobalSalt and getGlobalSalt used at startup (step 5)
+export {
+  GLOBAL_SALT_FILENAME,
+  GLOBAL_SALT_SIZE,
+  getGlobalSalt,
+  getGlobalSaltPath,
+  validateGlobalSalt,
+} from './store/global-salt.js';
+
 // ---------------------------------------------------------------------------
 // Agent Registry + Conduit (T170 Unification)
 // ---------------------------------------------------------------------------
@@ -855,4 +894,12 @@ export { ConduitClient } from './conduit/conduit-client.js';
 export { createConduit } from './conduit/factory.js';
 export { HttpTransport } from './conduit/http-transport.js';
 export { decrypt, encrypt } from './crypto/credentials.js';
-export { AgentRegistryAccessor } from './store/agent-registry-accessor.js';
+export {
+  AgentRegistryAccessor,
+  attachAgentToProject,
+  createProjectAgent,
+  detachAgentFromProject,
+  getProjectAgentRef,
+  listAgentsForProject,
+  lookupAgent,
+} from './store/agent-registry-accessor.js';

package/src/lifecycle/cant/lifecycle-rcasd.cant

@@ -0,0 +1,133 @@
+---
+kind: lifecycle
+version: 1.0.0
+title: "RCASD-IVTR+C Pipeline Stages"
+status: active
+---
+
+# RCASD-IVTR+C Pipeline Stage Definitions
+#
+# Canonical pipeline stages in execution order.
+# Source of truth: packages/core/src/lifecycle/stages.ts
+#
+# Stages: research, consensus, architecture_decision, specification,
+#   decomposition, implementation, validation, testing, release
+#
+# Cross-cutting stage: contribution (not part of pipeline execution order,
+#   tracked for attribution and provenance recording)
+#
+# Stage 1: Research
+#   order: 1
+#   category: planning
+#   description: Information gathering, exploration, and knowledge acquisition
+#   skippable: false
+#   defaultTimeoutHours: 48
+#   requiredGates: prerequisites-met
+#   expectedArtifacts: research-report, findings-document
+#
+# Stage 2: Consensus
+#   order: 2
+#   category: decision
+#   description: Multi-agent decision making and validation of research findings
+#   skippable: true
+#   defaultTimeoutHours: 24
+#   requiredGates: research-complete, agreement-reached
+#   expectedArtifacts: consensus-record, decision-log
+#
+# Stage 3: Architecture Decision
+#   order: 3
+#   category: decision
+#   description: Architecture Decision Records - documenting significant technical decisions
+#   skippable: true
+#   defaultTimeoutHours: 24
+#   requiredGates: decisions-documented, review-completed
+#   expectedArtifacts: adr-document
+#
+# Stage 4: Specification
+#   order: 4
+#   category: planning
+#   description: Specification writing - RFC-style documentation of requirements and design
+#   skippable: false
+#   defaultTimeoutHours: 72
+#   requiredGates: spec-complete, spec-reviewed
+#   expectedArtifacts: spec-document, api-spec, design-doc
+#
+# Stage 5: Decomposition
+#   order: 5
+#   category: planning
+#   description: Task breakdown - splitting work into atomic, executable tasks
+#   skippable: false
+#   defaultTimeoutHours: 24
+#   requiredGates: tasks-created, dependencies-mapped
+#   expectedArtifacts: task-breakdown, dependency-graph
+#
+# Stage 6: Implementation
+#   order: 6
+#   category: execution
+#   description: Implementation - writing code and building features
+#   skippable: false
+#   defaultTimeoutHours: none
+#   requiredGates: code-complete, lint-passing
+#   expectedArtifacts: source-code, implementation-notes
+#
+# Stage 7: Validation
+#   order: 7
+#   category: validation
+#   description: Verification - static analysis, type checking, and quality gates
+#   skippable: false
+#   defaultTimeoutHours: 12
+#   requiredGates: static-analysis-pass, type-check-pass
+#   expectedArtifacts: verification-report
+#
+# Stage 8: Testing
+#   order: 8
+#   category: validation
+#   description: Testing - running test suites and ensuring coverage
+#   skippable: false
+#   defaultTimeoutHours: 24
+#   requiredGates: tests-pass, coverage-met
+#   expectedArtifacts: test-results, coverage-report
+#
+# Stage 9: Release
+#   order: 9
+#   category: delivery
+#   description: Release - versioning, publishing, and deployment
+#   skippable: true
+#   defaultTimeoutHours: 4
+#   requiredGates: version-bumped, changelog-updated, artifacts-published
+#   expectedArtifacts: version-tag, release-notes, published-package
+#
+# Stage Categories:
+#   planning: research, specification, decomposition
+#   decision: consensus, architecture_decision
+#   execution: implementation
+#   validation: validation, testing
+#   delivery: release
+#
+# Prerequisites:
+#   research: (none)
+#   consensus: research
+#   architecture_decision: research, consensus
+#   specification: research, consensus, architecture_decision
+#   decomposition: research, specification
+#   implementation: research, specification, decomposition
+#   validation: implementation
+#   testing: implementation, validation
+#   release: implementation, validation, testing
+#
+# Transition Rules:
+#   Forward progressions (always allowed):
+#     research -> consensus -> architecture_decision -> specification
+#     specification -> decomposition -> implementation -> validation
+#     validation -> testing -> release
+#   Skip patterns (allowed with force):
+#     research -> specification (skipping consensus + architecture_decision)
+#     specification -> implementation (skipping decomposition)
+#   Backward transitions (allowed with force, for rework):
+#     implementation -> specification (rework required)
+#     testing -> implementation (fix test failures)
+#   Disallowed:
+#     release -> any (pipeline completed)
+#
+# Stage Status Values:
+#   not_started, in_progress, completed, skipped, blocked, failed

package/src/memory/__tests__/engine-compat.test.ts

@@ -37,7 +37,7 @@ const SAMPLE_ENTRIES = [
     date: '2026-01-15',
     status: 'completed',
     agent_type: 'research',
-    topics: ['mcp', 'engine'],
+    topics: ['async-ops', 'engine'],
     key_findings: ['finding1', 'finding2', 'finding3'],
     actionable: true,
     linked_tasks: ['T001'],
@@ -186,7 +186,7 @@ describe('Pipeline Manifest SQLite (moved from memory domain)', () => {
 
     it('should search by topic', async () => {
       await seedEntries();
-      const result = await pipelineManifestFind('mcp', {}, testRoot);
+      const result = await pipelineManifestFind('async-ops', {}, testRoot);
       expect(result.success).toBe(true);
       expect((result.data as any).total).toBeGreaterThan(0);
     });

package/src/memory/__tests__/pipeline-manifest-sqlite.test.ts

@@ -45,8 +45,8 @@ const ENTRY_A: ExtendedManifestEntry = {
   date: '2026-01-15',
   status: 'completed',
   agent_type: 'research',
-  topics: ['mcp', 'engine'],
-  key_findings: ['This library is deprecated', 'MCP supports structured output'],
+  topics: ['async-ops', 'engine'],
+  key_findings: ['This library is deprecated', 'System supports structured output'],
   actionable: true,
   linked_tasks: ['T001'],
   needs_followup: [],
@@ -464,9 +464,9 @@ describe('pipeline-manifest-sqlite', () => {
 
     it('should filter by topic param', async () => {
       await seedEntries(testRoot, [ENTRY_A, ENTRY_C]);
-      const result = await pipelineManifestContradictions(testRoot, { topic: 'mcp' });
+      const result = await pipelineManifestContradictions(testRoot, { topic: 'async-ops' });
       expect(result.success).toBe(true);
-      // ENTRY_C doesn't have 'mcp' topic, so no contradictions on that topic
+      // ENTRY_C doesn't have 'async-ops' topic, so no contradictions on that topic
       expect((result.data as any).contradictions.length).toBe(0);
     });
   });

package/src/observability/__tests__/index.test.ts

@@ -43,7 +43,7 @@ describe('queryLogs', () => {
         pid: 1,
         hostname: 'h',
         msg: 'Start',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'WARN',
@@ -273,7 +273,7 @@ describe('getLogSummary', () => {
         pid: 1,
         hostname: 'h',
         msg: 'a',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'INFO',
@@ -281,7 +281,7 @@ describe('getLogSummary', () => {
         pid: 2,
         hostname: 'h',
         msg: 'b',
-        subsystem: 'mcp',
+        subsystem: 'engine',
       }),
       JSON.stringify({
         level: 'WARN',
@@ -305,7 +305,7 @@ describe('getLogSummary', () => {
     const summary = getLogSummary({ scope: 'project' }, tmpDir);
     expect(summary.totalEntries).toBe(4);
     expect(summary.byLevel).toEqual({ INFO: 2, WARN: 1, ERROR: 1 });
-    expect(summary.bySubsystem).toEqual({ mcp: 2, engine: 2 });
+    expect(summary.bySubsystem).toEqual({ engine: 4 });
     expect(summary.dateRange).not.toBeNull();
     expect(summary.dateRange!.earliest).toBe('2026-02-28T10:00:00Z');
     expect(summary.dateRange!.latest).toBe('2026-02-28T10:03:00Z');

package/src/observability/__tests__/log-filter.test.ts

@@ -73,7 +73,7 @@ describe('matchesFilter', () => {
   it('filters by subsystem', () => {
     const entry = makeEntry({ subsystem: 'engine' });
     expect(matchesFilter(entry, { subsystem: 'engine' })).toBe(true);
-    expect(matchesFilter(entry, { subsystem: 'mcp' })).toBe(false);
+    expect(matchesFilter(entry, { subsystem: 'dispatch' })).toBe(false);
   });
 
   it('filters by code', () => {
@@ -105,7 +105,7 @@ describe('matchesFilter', () => {
   it('applies AND logic for multiple criteria', () => {
     const entry = makeEntry({ level: 'ERROR', subsystem: 'engine', code: 'E_NOT_FOUND' });
     expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'engine' })).toBe(true);
-    expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'mcp' })).toBe(false);
+    expect(matchesFilter(entry, { level: 'ERROR', subsystem: 'dispatch' })).toBe(false);
     expect(matchesFilter(entry, { level: 'WARN', subsystem: 'engine' })).toBe(false);
   });
 
@@ -119,10 +119,10 @@ describe('matchesFilter', () => {
 
 describe('filterEntries', () => {
   const entries = [
-    makeEntry({ level: 'INFO', msg: 'Starting server', subsystem: 'mcp' }),
+    makeEntry({ level: 'INFO', msg: 'Starting server', subsystem: 'dispatch' }),
     makeEntry({ level: 'WARN', msg: 'Task not found', subsystem: 'engine', code: 'E_NOT_FOUND' }),
     makeEntry({ level: 'ERROR', msg: 'Database locked', subsystem: 'engine', exitCode: 3 }),
-    makeEntry({ level: 'INFO', msg: 'Server stopped', subsystem: 'mcp' }),
+    makeEntry({ level: 'INFO', msg: 'Server stopped', subsystem: 'dispatch' }),
   ];
 
   it('returns all entries for empty filter', () => {

package/src/output.ts

@@ -4,22 +4,28 @@
  * LAFS (LLM-Agent-First Schema) ensures all CLI output is
  * machine-parseable JSON by default, with optional human-readable modes.
  *
- * All envelopes are now full LAFS-compliant with $schema and _meta.
- * The backward-compatible shape (success + data, no _meta) has been removed.
+ * All envelopes use the canonical CLI envelope shape:
+ *   { success, data?, error?, meta, page? }
+ *
+ * This replaces the three legacy shapes:
+ *   {ok, r, _m}            (minimal MVI — removed)
+ *   {$schema, _meta, success, result}  (full LAFS — now uses meta/data)
+ *   {success, result}      (observe command — now uses data)
  *
  * Types are re-exported from the canonical source in src/types/lafs.ts.
  *
  * @epic T4663
  * @task T4672
+ * @task T338 (ADR-039 envelope unification)
  */
 
 import { randomUUID } from 'node:crypto';
 import type { LafsEnvelope, LafsError, LafsSuccess } from '@cleocode/contracts';
-import type { LAFSMeta, LAFSPage, Warning } from '@cleocode/lafs';
+import type { CliEnvelope, CliEnvelopeError, CliMeta, LAFSPage, Warning } from '@cleocode/lafs';
 import { CleoError } from './errors.js';
 import { getCurrentSessionId } from './sessions/context-alert.js';
 
-export type { LafsEnvelope, LafsError, LafsSuccess };
+export type { CliEnvelope, CliEnvelopeError, CliMeta, LafsEnvelope, LafsError, LafsSuccess };
 
 /**
  * Accumulated warnings for the current request.
@@ -70,47 +76,57 @@ export interface FormatOptions {
 }
 
 /**
- * Create a LAFS-conformant _meta object for CLI envelopes.
+ * Create a canonical `CliMeta` object for CLI envelopes.
+ *
  * Includes sessionId (T4702) and warnings (T4669) when present.
+ * Drains the pending warnings queue so they are included in the current envelope.
+ *
+ * @param operation - Dot-delimited operation identifier (e.g. `"tasks.show"`).
+ * @param duration_ms - Wall-clock duration in milliseconds. Defaults to 0.
+ * @returns A fully populated {@link CliMeta} object.
  *
  * @task T4700
  * @task T4702
+ * @task T338
  * @epic T4663
  */
-function createCliMeta(
-  operation: string,
-  mvi: import('@cleocode/lafs').MVILevel = 'minimal',
-): LAFSMeta {
+function createCliMeta(operation: string, duration_ms = 0): CliMeta {
   const warnings = drainWarnings();
-  const meta: LAFSMeta = {
-    specVersion: '1.2.3',
-    schemaVersion: '2026.2.1',
-    timestamp: new Date().toISOString(),
+  const meta: CliMeta = {
     operation,
     requestId: randomUUID(),
-    transport: 'cli',
-    strict: true,
-    mvi,
-    contextVersion: 1,
-    ...(warnings && { warnings }),
+    duration_ms,
+    timestamp: new Date().toISOString(),
   };
   const sessionId = getCurrentSessionId();
   if (sessionId) {
-    meta.sessionId = sessionId;
+    meta['sessionId'] = sessionId;
+  }
+  if (warnings && warnings.length > 0) {
+    meta['warnings'] = warnings;
   }
   return meta;
 }
 
 /**
- * Format a successful result as a full LAFS-conformant envelope.
+ * Format a successful result as a canonical CLI envelope.
+ *
+ * Produces the unified `CliEnvelope<T>` shape: `{success, data, meta, page?}`.
+ * This replaces all three legacy shapes (minimal `{ok,r,_m}`, full `{$schema,_meta,result}`,
+ * and observe `{success,result}`) with a single canonical format (ADR-039).
+ *
+ * The `mvi` option in `FormatOptions` is accepted for backward compatibility but
+ * no longer affects the envelope shape — the canonical shape is always emitted.
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
- * Supports optional page (T4668) and _extensions (T4670).
+ * @param data - The operation result payload.
+ * @param message - Optional success message (attached to `meta.message`).
+ * @param operationOrOpts - Operation name string or `FormatOptions` object.
+ * @returns JSON-serialized `CliEnvelope<T>`.
  *
  * @task T4672
  * @task T4668
  * @task T4670
+ * @task T338
  * @epic T4663
  */
 export function formatSuccess<T>(
@@ -121,71 +137,53 @@ export function formatSuccess<T>(
   const opts: FormatOptions =
     typeof operationOrOpts === 'string' ? { operation: operationOrOpts } : (operationOrOpts ?? {});
 
-  // Determine MVI level: default is 'minimal' (agent-optimized).
-  // Only --human flag or explicit mvi='full'/'standard' overrides.
-  const mviLevel = opts.mvi ?? 'minimal';
+  const meta = createCliMeta(opts.operation ?? 'cli.output');
 
-  const meta = createCliMeta(opts.operation ?? 'cli.output', mviLevel);
-  const fullEnvelope: Record<string, unknown> = {
-    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
-    _meta: meta,
-    success: true as const,
-    result: data as Record<string, unknown> | Record<string, unknown>[] | null,
-    ...(message && { message }),
+  const envelope: CliEnvelope<T> = {
+    success: true,
+    data,
+    meta: message ? { ...meta, message } : meta,
     ...(opts.page && { page: opts.page }),
-    ...(opts.extensions &&
-      Object.keys(opts.extensions).length > 0 && { _extensions: opts.extensions }),
   };
 
-  // For 'full' level, skip projection — return the complete envelope as-is.
-  // This is the backward-compatible path used by --human and conformance tests.
-  if (mviLevel === 'full') {
-    return JSON.stringify(fullEnvelope);
-  }
-
-  // Apply MVI projection — strips envelope to the declared level.
-  // 'minimal': { success, result, _meta: { requestId, contextVersion } }
-  // 'standard': + $schema, timestamp, operation, mvi
-  if (mviLevel === 'minimal') {
-    // Inline minimal projection — avoids dynamic import overhead.
-    // Matches projectMetaMinimal() from @cleocode/lafs/mviProjection.ts
-    const minimalMeta: Record<string, unknown> = {
-      op: meta.operation,
-      rid: meta.requestId,
-    };
-    if (meta.sessionId) minimalMeta.sid = meta.sessionId;
-    if (meta.warnings?.length) minimalMeta.w = meta.warnings;
-
-    const minimal: Record<string, unknown> = {
-      ok: true,
-      r: data,
-      _m: minimalMeta,
-    };
-    if (message) minimal.msg = message;
-    if (opts.page) minimal.p = opts.page;
-    return JSON.stringify(minimal);
-  }
-
-  // 'standard' level — use the full envelope structure (current behavior)
-  return JSON.stringify(fullEnvelope);
+  return JSON.stringify(envelope);
 }
 
 /**
- * Format an error as a full LAFS-conformant envelope.
+ * Format an error as a canonical CLI error envelope.
+ *
+ * Produces `{success: false, error: CliEnvelopeError, meta: CliMeta}`.
+ * Every error envelope now always includes `meta` (ADR-039).
+ * When operation is omitted, defaults to `'cli.output'`.
  *
- * Always produces the full LAFSEnvelope with $schema and _meta.
- * When operation is omitted, defaults to 'cli.output'.
+ * @param error - The `CleoError` to format.
+ * @param operation - Optional dot-delimited operation identifier.
+ * @returns JSON-serialized error `CliEnvelope`.
  *
  * @task T4672
+ * @task T338
  * @epic T4663
  */
 export function formatError(error: CleoError, operation?: string): string {
-  const envelope = {
-    $schema: 'https://lafs.dev/schemas/v1/envelope.schema.json',
-    _meta: createCliMeta(operation ?? 'cli.output'),
-    success: false as const,
-    result: null,
-    error: error.toLAFSError(),
+  const lafsError = error.toLAFSError();
+  const errorObj: CliEnvelopeError = {
+    code: lafsError.code,
+    message: lafsError.message,
+    details: lafsError.details,
+  };
+  if ('category' in lafsError && lafsError.category) {
+    (errorObj as Record<string, unknown>)['category'] = lafsError.category;
+  }
+  if ('retryable' in lafsError) {
+    (errorObj as Record<string, unknown>)['retryable'] = lafsError.retryable;
+  }
+  if ('agentAction' in lafsError && lafsError.agentAction) {
+    (errorObj as Record<string, unknown>)['agentAction'] = lafsError.agentAction;
+  }
+  const envelope: CliEnvelope<null> = {
+    success: false,
+    error: errorObj,
+    meta: createCliMeta(operation ?? 'cli.output'),
   };
   return JSON.stringify(envelope);
 }

package/src/sessions/__tests__/session-grade.integration.test.ts

@@ -160,7 +160,7 @@ function sloppySession(): AuditEntry[] {
       params: { title: 'Do something', description: 'Duplicate' },
       result: { success: true, exitCode: 0, duration: 20 },
     }),
-    // No session.end, no help calls, no MCP gateway
+    // No session.end, no help calls, no query gateway usage
   ];
 }