@cleocode/core 2026.4.12 → 2026.4.14

package/dist/store/sqlite-backup.d.ts

@@ -2,14 +2,17 @@
  * SQLite backup via VACUUM INTO with snapshot rotation.
  *
  * Produces self-contained, WAL-free copies of CLEO SQLite databases
- * (tasks.db, brain.db at project tier; nexus.db at global tier) into
- * `.cleo/backups/sqlite/` (project) or `$XDG_DATA_HOME/cleo/backups/sqlite/`
- * (global) with a configurable rotation limit. All errors are swallowed —
- * backup failure must never interrupt normal operation.
+ * (tasks.db, brain.db, conduit.db at project tier; nexus.db, signaldock.db at
+ * global tier) into `.cleo/backups/sqlite/` (project) or
+ * `$XDG_DATA_HOME/cleo/backups/sqlite/` (global) with a configurable rotation
+ * limit. Also provides raw-file backup for the global-salt binary (not SQLite).
+ * All errors are swallowed — backup failure must never interrupt normal operation.
  *
  * @task T4873
  * @task T5158 — extended to cover brain.db
  * @task T306  — extended to cover global-tier nexus.db (epic T299)
+ * @task T369  — extended to cover conduit.db (project), signaldock.db (global),
+ *               and global-salt raw-file backup (epic T310)
  * @epic T4867
  */
 /** Options accepted by {@link vacuumIntoBackup} and {@link vacuumIntoBackupAll}. */
@@ -96,12 +99,13 @@ export type BackupScope = 'project' | 'global';
  * Non-fatal: errors from any individual step are surfaced via the return value
  * but never thrown — a failed snapshot MUST NOT interrupt normal operation.
  *
- * @param dbName         - Which global-tier DB to snapshot (`'nexus'`; `'signaldock'` reserved for T310)
+ * @param dbName         - Which global-tier DB to snapshot (`'nexus'` or `'signaldock'`)
  * @param opts.rotation  - Maximum retained snapshots per prefix (default 10)
  * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
  * @returns Object containing the new snapshot path and any rotated (deleted) file paths
  *
  * @task T306
+ * @task T369 — activated signaldock target (epic T310)
  * @epic T299
  * @why ADR-036 §Backup Mechanism requires VACUUM INTO rotation at the global tier;
  *      nexus.db has zero backup coverage prior to v2026.4.11.
@@ -142,4 +146,55 @@ export interface GlobalBackupEntry {
  * @epic T299
  */
 export declare function listGlobalSqliteBackups(prefix?: string, cleoHomeOverride?: string): GlobalBackupEntry[];
+/**
+ * Creates a raw-file backup of the global-salt binary at
+ * `${getCleoHome()}/backups/global-salt-YYYYMMDD-HHmmss` with `0o600`
+ * permissions. Rotates to {@link MAX_SNAPSHOTS} (10) copies, deleting the
+ * oldest when the limit is reached.
+ *
+ * Non-fatal: errors are swallowed — salt backup failure must never block cleo.
+ * Returns empty strings and no rotated paths on failure.
+ *
+ * @param opts.cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ * @returns Object with the new snapshot path and any rotated (deleted) file paths
+ *
+ * @task T369
+ * @epic T310
+ * @why ADR-037 §5 — global-salt is security-critical; losing it invalidates
+ *      all API keys. Backup enables recovery from accidental deletion.
+ */
+export declare function backupGlobalSalt(opts?: {
+    cleoHomeOverride?: string;
+}): Promise<{
+    snapshotPath: string;
+    rotated: string[];
+}>;
+/**
+ * A single entry returned by {@link listGlobalSaltBackups}.
+ *
+ * @task T369
+ * @epic T310
+ */
+export interface GlobalSaltBackupEntry {
+    /** Backup filename, e.g. `global-salt-20260408-143022`. */
+    name: string;
+    /** Absolute path to the backup file. */
+    path: string;
+    /** File size in bytes (should be 32 for a valid global-salt). */
+    size: number;
+    /** Last-modified timestamp. */
+    mtime: Date;
+}
+/**
+ * List global-salt backup files from `$XDG_DATA_HOME/cleo/backups/`, sorted
+ * newest-first by mtime.
+ *
+ * Returns an empty array when the backup directory does not exist.
+ *
+ * @param cleoHomeOverride - Override `getCleoHome()` path (use in tests to target a tmp dir)
+ *
+ * @task T369
+ * @epic T310
+ */
+export declare function listGlobalSaltBackups(cleoHomeOverride?: string): GlobalSaltBackupEntry[];
 //# sourceMappingURL=sqlite-backup.d.ts.map

package/dist/store/sqlite-backup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sqlite-backup.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6FH,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjF;AA8BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAMxE;AAQD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAmB/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,OAAO,GAAG,YAAY,EAC9B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsDtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACxB,iBAAiB,EAAE,CAkBrB"}
+{"version":3,"file":"sqlite-backup.d.ts","sourceRoot":"","sources":["../../src/store/sqlite-backup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA6GH,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAuCD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB9E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,mBAAmB,CAAC,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyBjF;AA8BD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,CAAC,EAAE,MAAM,GACX,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,CAAC,EAAE,MAAM,GACX,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAMxE;AAQD;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAyB/C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,OAAO,GAAG,YAAY,EAC9B,IAAI,CAAC,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CAsDtD;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE,MAAM,EACf,gBAAgB,CAAC,EAAE,MAAM,GACxB,iBAAiB,EAAE,CAkBrB;AAyDD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,CAAC,EAAE;IAC5C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,GAAG,OAAO,CAAC;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2BvD;AAED;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,+BAA+B;IAC/B,KAAK,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,qBAAqB,EAAE,CAgBxF"}

package/dist/store/t310-readiness.d.ts

@@ -0,0 +1,83 @@
+/**
+ * T310-readiness gate: detect conduit.db vs legacy signaldock.db at project tier.
+ *
+ * T311 backup/restore code paths reference `.cleo/conduit.db` (project tier) and
+ * `$XDG_DATA_HOME/cleo/signaldock.db` (global tier) per ADR-037. A project that
+ * has not yet been migrated (still has `.cleo/signaldock.db` without a
+ * `.cleo/conduit.db`) will confuse T311 export/import commands. This gate runs
+ * as a precondition on every T311 CLI verb.
+ *
+ * @task T342
+ * @epic T311
+ * @why T311 export/import references .cleo/conduit.db (project tier) and
+ *      $XDG_DATA_HOME/cleo/signaldock.db (global tier) per ADR-037.
+ *      If the current project is still on the pre-T310 topology, T311
+ *      commands must surface a clear error telling the user to run a
+ *      cleo command first to trigger migration.
+ * @what Throws T310MigrationRequiredError with instructions if legacy
+ *       signaldock.db exists AND conduit.db does not.
+ */
+/**
+ * Thrown by `assertT310Ready` when the current project is still on the
+ * pre-T310 topology: `.cleo/signaldock.db` is present but `.cleo/conduit.db`
+ * is absent. T311 commands cannot proceed until migration has run.
+ *
+ * @task T342
+ * @epic T311
+ */
+export declare class T310MigrationRequiredError extends Error {
+    readonly projectRoot: string;
+    /**
+     * @param projectRoot - Absolute path to the project root that needs migration.
+     */
+    constructor(projectRoot: string);
+}
+/**
+ * Asserts the current project is on the post-T310 topology. Does nothing
+ * if conduit.db exists (migration already ran) OR if no legacy signaldock.db
+ * exists (fresh install — no migration needed).
+ *
+ * Throws when legacy signaldock.db is present AND conduit.db is absent,
+ * which indicates the project has not yet been migrated to the T310 topology
+ * expected by T311 backup/restore commands.
+ *
+ * @param projectRoot - Absolute path to the project root. Defaults to
+ *   `getProjectRoot()` (walks ancestors for `.cleo/` sentinel).
+ * @throws {T310MigrationRequiredError} if legacy signaldock.db exists
+ *   without conduit.db at the project tier.
+ *
+ * @task T342
+ * @epic T311
+ *
+ * @example
+ * ```typescript
+ * // Precondition guard at the top of every T311 CLI verb handler:
+ * assertT310Ready();
+ * ```
+ */
+export declare function assertT310Ready(projectRoot?: string): void;
+/**
+ * Returns true if T311 commands can safely run on the current project.
+ *
+ * This is the non-throwing companion to `assertT310Ready`. Returns false
+ * only when the pre-T310 topology is detected (legacy signaldock.db exists
+ * without conduit.db). All other states — fresh installs, fully-migrated
+ * projects — return true.
+ *
+ * @param projectRoot - Absolute path to the project root. Defaults to
+ *   `getProjectRoot()` (walks ancestors for `.cleo/` sentinel).
+ * @returns `true` if the project is on the post-T310 topology or is a fresh
+ *   install; `false` if migration is required.
+ *
+ * @task T342
+ * @epic T311
+ *
+ * @example
+ * ```typescript
+ * if (!isT310Ready()) {
+ *   console.error('Run `cleo version` to trigger T310 migration first.');
+ * }
+ * ```
+ */
+export declare function isT310Ready(projectRoot?: string): boolean;
+//# sourceMappingURL=t310-readiness.d.ts.map

package/dist/store/t310-readiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"t310-readiness.d.ts","sourceRoot":"","sources":["../../src/store/t310-readiness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH;;;;;;;GAOG;AACH,qBAAa,0BAA2B,SAAQ,KAAK;aAIvB,WAAW,EAAE,MAAM;IAH/C;;OAEG;gBACyB,WAAW,EAAE,MAAM;CAQhD;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAQ1D;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAQzD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.4.12",
+  "version": "2026.4.14",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     }
   },
   "dependencies": {
-    "@xenova/transformers": "^2.17.2",
+    "@huggingface/transformers": "^4.0.1",
     "ajv": "^8.18.0",
     "ajv-formats": "^3.0.1",
     "drizzle-orm": "1.0.0-beta.19-d95b7a4",
@@ -32,15 +32,16 @@
     "pino": "^10.3.1",
     "pino-roll": "^4.0.0",
     "proper-lockfile": "^4.1.2",
+    "tar": "^7.4.3",
     "write-file-atomic": "^6.0.0",
-    "yaml": "^2.8.2",
+    "yaml": "^2.8.3",
     "zod": "^3.25.76",
-    "@cleocode/adapters": "2026.4.12",
-    "@cleocode/agents": "2026.4.12",
-    "@cleocode/contracts": "2026.4.12",
-    "@cleocode/caamp": "2026.4.12",
-    "@cleocode/lafs": "2026.4.12",
-    "@cleocode/skills": "2026.4.12"
+    "@cleocode/agents": "2026.4.14",
+    "@cleocode/contracts": "2026.4.14",
+    "@cleocode/lafs": "2026.4.14",
+    "@cleocode/caamp": "2026.4.14",
+    "@cleocode/adapters": "2026.4.14",
+    "@cleocode/skills": "2026.4.14"
   },
   "optionalDependencies": {
     "tree-sitter-c": "^0.24.1",
@@ -70,6 +71,7 @@
   ],
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4",
+    "@types/tar": "^6.1.13",
     "@types/write-file-atomic": "^4.0.3"
   },
   "repository": {

package/src/__tests__/cli-parity.test.ts

@@ -172,20 +172,22 @@ describe('Exit Code Parity', () => {
 // LAFS Envelope Format Parity
 // ============================================================
 
-describe('LAFS Envelope Format', () => {
-  it('success envelope is full LAFS with $schema and _meta', () => {
+describe('Canonical CLI Envelope Format (ADR-039)', () => {
+  it('success envelope uses canonical CLI shape { success, data, meta }', () => {
     const result = formatSuccess({ task: { id: 'T001', title: 'Test' } });
     const parsed = JSON.parse(result);
 
-    // Full LAFS envelope: { $schema, _meta, success: true, result: {...} }
-    expect(parsed.$schema).toBe('https://lafs.dev/schemas/v1/envelope.schema.json');
-    expect(parsed._meta).toBeDefined();
+    // Canonical CLI envelope (ADR-039): { success, data, meta } — no $schema, no _meta, no result.
+    expect(parsed.$schema).toBeUndefined();
+    expect(parsed._meta).toBeUndefined();
+    expect(parsed.result).toBeUndefined();
+    expect(parsed.meta).toBeDefined();
     expect(parsed.success).toBe(true);
-    expect(parsed.result).toBeDefined();
-    expect(parsed.result.task).toBeDefined();
+    expect(parsed.data).toBeDefined();
+    expect(parsed.data.task).toBeDefined();
   });
 
-  it('error envelope is full LAFS with $schema and _meta', () => {
+  it('error envelope uses canonical CLI shape { success, error, meta }', () => {
     const err = new CleoError(ExitCode.NOT_FOUND, 'Task T999 not found', {
       fix: 'Use cleo list to find tasks',
       alternatives: [{ action: 'Search', command: 'cleo find query' }],
@@ -193,9 +195,11 @@ describe('LAFS Envelope Format', () => {
     const result = formatError(err);
     const parsed = JSON.parse(result);
 
-    // Full LAFS envelope: { $schema, _meta, success: false, result: null, error: {...} }
-    expect(parsed.$schema).toBe('https://lafs.dev/schemas/v1/envelope.schema.json');
-    expect(parsed._meta).toBeDefined();
+    // Canonical CLI envelope (ADR-039): { success: false, error, meta } — no $schema, no _meta, no result.
+    expect(parsed.$schema).toBeUndefined();
+    expect(parsed._meta).toBeUndefined();
+    expect(parsed.result).toBeUndefined();
+    expect(parsed.meta).toBeDefined();
     expect(parsed.success).toBe(false);
     expect(parsed.error).toBeDefined();
     expect(parsed.error.code).toMatch(/^E_CLEO_NOT_FOUND/);
@@ -204,7 +208,7 @@ describe('LAFS Envelope Format', () => {
     expect(parsed.error.details.alternatives).toHaveLength(1);
   });
 
-  it('CleoError.toJSON matches LAFS envelope', () => {
+  it('CleoError.toJSON matches legacy error shape', () => {
     const err = new CleoError(ExitCode.VALIDATION_ERROR, 'Bad input');
     const json = err.toJSON();
     expect(json.success).toBe(false);
@@ -212,11 +216,12 @@ describe('LAFS Envelope Format', () => {
     expect((json.error as Record<string, unknown>).name).toBe('VALIDATION_ERROR');
   });
 
-  it('success with noChange flag', () => {
+  it('success with noChange flag attaches message to meta.message', () => {
     const result = formatSuccess(null, 'No changes needed');
     const parsed = JSON.parse(result);
     expect(parsed.success).toBe(true);
-    expect(parsed.message).toBe('No changes needed');
+    // ADR-039: message is now carried in meta.message, not at the top level.
+    expect(parsed.meta.message).toBe('No changes needed');
   });
 });
 

package/src/__tests__/human-output.test.ts

@@ -98,8 +98,8 @@ describe('--human output verification (T4696)', () => {
     });
   });
 
-  describe('LAFS envelopes are valid regardless of format flags', () => {
-    it('formatSuccess produces valid JSON for show operation', () => {
+  describe('Canonical CLI envelopes are valid regardless of format flags (ADR-039)', () => {
+    it('formatSuccess produces canonical envelope for show operation', () => {
       const json = formatSuccess(
         {
           task: { id: 'T4663', title: 'Wave 8: Full System Integration', status: 'active' },
@@ -110,12 +110,14 @@ describe('--human output verification (T4696)', () => {
       const parsed = JSON.parse(json);
 
       expect(parsed.success).toBe(true);
-      expect(parsed.$schema).toBeDefined();
-      expect(parsed._meta).toBeDefined();
-      expect(parsed.result.task.id).toBe('T4663');
+      // ADR-039: canonical shape drops $schema and _meta; payload lives in data.
+      expect(parsed.$schema).toBeUndefined();
+      expect(parsed._meta).toBeUndefined();
+      expect(parsed.meta).toBeDefined();
+      expect(parsed.data.task.id).toBe('T4663');
     });
 
-    it('formatSuccess produces valid JSON for list operation', () => {
+    it('formatSuccess produces canonical envelope for list operation', () => {
       const json = formatSuccess(
         {
           tasks: [
@@ -130,11 +132,11 @@ describe('--human output verification (T4696)', () => {
       const parsed = JSON.parse(json);
 
       expect(parsed.success).toBe(true);
-      expect(parsed.result.tasks).toHaveLength(2);
-      expect(parsed.result.total).toBe(2);
+      expect(parsed.data.tasks).toHaveLength(2);
+      expect(parsed.data.total).toBe(2);
     });
 
-    it('formatSuccess produces valid JSON for dash operation', () => {
+    it('formatSuccess produces canonical envelope for dash operation', () => {
       const json = formatSuccess(
         {
           project: { name: 'cleo' },
@@ -146,8 +148,8 @@ describe('--human output verification (T4696)', () => {
       const parsed = JSON.parse(json);
 
       expect(parsed.success).toBe(true);
-      expect(parsed.result.project.name).toBe('cleo');
-      expect(parsed.result.stats.total).toBe(50);
+      expect(parsed.data.project.name).toBe('cleo');
+      expect(parsed.data.stats.total).toBe(50);
     });
 
     it('formatError produces valid JSON with fix suggestions', () => {

package/src/init.ts

@@ -521,7 +521,14 @@ export async function updateDocs(): Promise<InitResult> {
  */
 export async function initProject(opts: InitOptions = {}): Promise<InitResult> {
   const cleoDir = getCleoDirAbsolute();
-  const projRoot = getProjectRoot();
+  // `cleo init` CREATES the project root, so we cannot call getProjectRoot()
+  // here — that walks up looking for an existing `.cleo/` sentinel and throws
+  // `E_NOT_FOUND` when none is present (the whole point of `init` is that
+  // none is present yet). `cleoDir` is `<cwd>/.cleo` by default, so its
+  // parent directory is the project root. This also respects an absolute
+  // `CLEO_DIR` env var used by the init-e2e test suite to pin the target
+  // directory.
+  const projRoot = dirname(cleoDir);
 
   // Guard: fail if project already initialized (unless --force)
   const alreadyInitialized =
@@ -586,16 +593,19 @@ export async function initProject(opts: InitOptions = {}): Promise<InitResult> {
     created.push(`brain.db (deferred: ${err instanceof Error ? err.message : String(err)})`);
   }
 
-  // Initialize signaldock.db for local agent messaging infrastructure (T223)
+  // Initialize conduit.db for project-tier agent messaging infrastructure.
+  // T310 (v2026.4.12) moved project-tier messaging from signaldock.db to
+  // conduit.db; global agent identity continues to live in the global
+  // signaldock.db, which the CLI startup sequence ensures separately.
   try {
-    const { ensureSignaldockDb } = await import('./store/signaldock-sqlite.js');
-    const sdResult = await ensureSignaldockDb(projRoot);
-    if (sdResult.action === 'created') {
-      created.push('signaldock.db');
+    const { ensureConduitDb } = await import('./store/conduit-sqlite.js');
+    const cdResult = ensureConduitDb(projRoot);
+    if (cdResult.action === 'created') {
+      created.push('conduit.db');
     }
   } catch (err) {
-    // Non-fatal — signaldock.db will be created on first agent operation
-    created.push(`signaldock.db (deferred: ${err instanceof Error ? err.message : String(err)})`);
+    // Non-fatal — conduit.db will be created on first agent operation
+    created.push(`conduit.db (deferred: ${err instanceof Error ? err.message : String(err)})`);
   }
 
   // T4681: Create .cleo/.gitignore (respect force flag)

package/src/internal.ts

@@ -410,6 +410,9 @@ export { listStickies, purgeSticky } from './sticky/index.js';
 export type { CreateStickyParams, ListStickiesParams, StickyNote } from './sticky/types.js';
 // Store
 export { createBackup, listBackups, restoreFromBackup } from './store/backup.js';
+// Backup portability — bundle packer (T311 / T347)
+export type { PackBundleInput, PackBundleResult } from './store/backup-pack.js';
+export { packBundle } from './store/backup-pack.js';
 export { getBrainDb, getBrainNativeDb } from './store/brain-sqlite.js';
 export type { LegacyCleanupResult, StrayNexusCleanupResult } from './store/cleanup-legacy.js';
 export {
@@ -442,7 +445,11 @@ export {
   SIGNALDOCK_SCHEMA_VERSION,
 } from './store/signaldock-sqlite.js';
 export { getDb, getNativeDb } from './store/sqlite.js';
-export type { BackupScope, GlobalBackupEntry, GlobalSaltBackupEntry } from './store/sqlite-backup.js';
+export type {
+  BackupScope,
+  GlobalBackupEntry,
+  GlobalSaltBackupEntry,
+} from './store/sqlite-backup.js';
 export {
   backupGlobalSalt,
   listBrainBackups,
@@ -696,11 +703,51 @@ export { readSnapshot } from './snapshot/index.js';
 export { addSticky } from './sticky/create.js';
 export { getSticky } from './sticky/index.js';
 
+// Store — backup crypto (T363)
+export { decryptBundle, encryptBundle, isEncryptedBundle } from './store/backup-crypto.js';
+
 // Store (additional)
 export { resolveProjectRoot } from './store/file-utils.js';
 export { TASK_PRIORITIES } from './store/tasks-schema.js';
 // System (additional)
 export type { MigrateResult } from './system/index.js';
+
+// ---------------------------------------------------------------------------
+// T311 Backup portability — unpack + verify + A/B restore (T350, T352, T354, T357)
+// ---------------------------------------------------------------------------
+
+// Unpack + verify (T350)
+export type {
+  SchemaCompatWarning as BundleSchemaCompatWarning,
+  UnpackBundleInput,
+  UnpackBundleResult,
+} from './store/backup-unpack.js';
+export { BundleError, cleanupStaging, unpackBundle } from './store/backup-unpack.js';
+// Dry-run JSON file generators (T352)
+export type { RegeneratedFile } from './store/regenerators.js';
+export {
+  regenerateAllJson,
+  regenerateConfigJson,
+  regenerateProjectContextJson,
+  regenerateProjectInfoJson,
+} from './store/regenerators.js';
+// Conflict report formatter (T357)
+export type {
+  BuildConflictReportInput,
+  ReauthWarning,
+  SchemaCompatWarning as RestoreSchemaCompatWarning,
+} from './store/restore-conflict-report.js';
+export { buildConflictReport, writeConflictReport } from './store/restore-conflict-report.js';
+// A/B regenerate-and-compare engine (T354)
+export type {
+  FieldCategory,
+  FieldClassification,
+  FilenameForRestore,
+  JsonRestoreReport,
+  RegenerateAndCompareInput,
+  Resolution,
+} from './store/restore-json-merge.js';
+export { regenerateAndCompare, regenerateAndCompareAll } from './store/restore-json-merge.js';
 // Tasks (additional — stats)
 export { coreTaskStats } from './tasks/task-ops.js';
 
@@ -867,11 +914,14 @@ export { checkRootGitignore } from './validation/doctor/checks.js';
 // ---------------------------------------------------------------------------
 
 // Conduit DB lifecycle — ensureConduitDb is called at every CLI startup (step 3)
-export type { ProjectAgentRef } from './store/conduit-sqlite.js';
+// ProjectAgentRef lives in @cleocode/contracts; conduit-sqlite.ts only imports it.
+// We re-export from the canonical source here to keep the internal barrel stable.
+export type { ProjectAgentRef } from '@cleocode/contracts';
 export {
   CONDUIT_DB_FILENAME,
   CONDUIT_SCHEMA_VERSION,
   checkConduitDbHealth,
+  closeConduitDb,
   ensureConduitDb,
   getConduitDbPath,
   getConduitNativeDb,

package/src/memory/__tests__/brain-automation.test.ts

@@ -69,8 +69,8 @@ vi.mock('../../store/data-accessor.js', () => ({
   }),
 }));
 
-// Mock @xenova/transformers to prevent model downloads in tests
-vi.mock('@xenova/transformers', () => ({
+// Mock @huggingface/transformers to prevent model downloads in tests
+vi.mock('@huggingface/transformers', () => ({
   pipeline: vi
     .fn()
     .mockResolvedValue(vi.fn().mockResolvedValue({ data: new Float32Array(384).fill(0.1) })),

package/src/memory/brain-embedding.ts

@@ -72,7 +72,7 @@ export function isEmbeddingAvailable(): boolean {
  * setEmbeddingProvider(). Should be called once at startup when
  * `brain.embedding.enabled` is true.
  *
- * Uses dynamic import to avoid loading the heavy @xenova/transformers
+ * Uses dynamic import to avoid loading the heavy @huggingface/transformers
  * bundle unless embedding is actually requested.
  *
  * @task T136 @epic T134

package/src/memory/embedding-local.ts

@@ -1,5 +1,5 @@
 /**
- * Local embedding provider using @xenova/transformers.
+ * Local embedding provider using @huggingface/transformers (transformers.js v4).
  *
  * Implements the EmbeddingProvider interface for brain memory vector search.
  * Uses all-MiniLM-L6-v2 (22MB, 384 dimensions) — matches the brain_embeddings
@@ -9,7 +9,12 @@
  * @epic T134
  * @task T136
  * @why Ship vector search out-of-the-box without external API keys
- * @what Local embedding provider using @xenova/transformers all-MiniLM-L6-v2
+ * @what Local embedding provider using @huggingface/transformers all-MiniLM-L6-v2
+ * @remarks Migrated from @xenova/transformers (v2) to @huggingface/transformers
+ *   (v4) — the upstream rename, same author. v4 drops the deprecated
+ *   prebuild-install transitive (via sharp@0.34+) and ships with newer
+ *   onnxruntime. Public API (`pipeline`, `FeatureExtractionPipeline`) is
+ *   unchanged; Xenova-hosted models still resolve by their original names.
  */
 
 import type { EmbeddingProvider } from './brain-embedding.js';
@@ -19,7 +24,7 @@ import { EMBEDDING_DIMENSIONS } from './brain-embedding.js';
 const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
 
 /** Pipeline singleton — initialized lazily on first call. */
-let _pipeline: import('@xenova/transformers').FeatureExtractionPipeline | null = null;
+let _pipeline: import('@huggingface/transformers').FeatureExtractionPipeline | null = null;
 
 /** Whether the pipeline has been successfully initialized. */
 let _ready = false;
@@ -31,13 +36,13 @@ let _ready = false;
 async function loadPipeline(): Promise<void> {
   if (_ready) return;
   // Dynamic import — only resolves when embedding is explicitly enabled
-  const { pipeline } = await import('@xenova/transformers');
+  const { pipeline } = await import('@huggingface/transformers');
   _pipeline = await pipeline('feature-extraction', MODEL_NAME);
   _ready = true;
 }
 
 /**
- * Local embedding provider backed by @xenova/transformers.
+ * Local embedding provider backed by @huggingface/transformers.
  *
  * Produces 384-dimension Float32Array vectors compatible with the
  * brain_embeddings vec0 table. The model is downloaded on first use

package/src/memory/embedding-worker.ts

@@ -12,7 +12,7 @@
  *
  * @epic T134
  * @task T137
- * @why Prevent @xenova/transformers model inference from blocking the main thread
+ * @why Prevent @huggingface/transformers model inference from blocking the main thread
  * @what Worker thread script for async embedding generation
  */
 

package/src/skills/__tests__/discovery.test.ts

@@ -217,13 +217,28 @@ describe('toSkillSummary', () => {
 
 describe('getSkillSearchPaths', () => {
   it('should return ordered search paths', () => {
-    const paths = getSkillSearchPaths(testDir);
-
-    // Returns paths that exist on disk; may be 0 or more depending on environment
-    expect(Array.isArray(paths)).toBe(true);
-    // Should be in priority order
-    for (let i = 1; i < paths.length; i++) {
-      expect(paths[i].priority).toBeGreaterThanOrEqual(paths[i - 1].priority);
+    // Pin the project root to the isolated test dir via CLEO_ROOT (the
+    // escape hatch documented in paths.ts). Without this, the test
+    // depends on the worker process cwd happening to live inside a
+    // CLEO project (true locally when running from the monorepo, false
+    // on CI where the checkout has no `.cleo/` sentinel).
+    const savedRoot = process.env['CLEO_ROOT'];
+    process.env['CLEO_ROOT'] = testDir;
+    try {
+      const paths = getSkillSearchPaths(testDir);
+
+      // Returns paths that exist on disk; may be 0 or more depending on environment
+      expect(Array.isArray(paths)).toBe(true);
+      // Should be in priority order
+      for (let i = 1; i < paths.length; i++) {
+        expect(paths[i].priority).toBeGreaterThanOrEqual(paths[i - 1].priority);
+      }
+    } finally {
+      if (savedRoot === undefined) {
+        delete process.env['CLEO_ROOT'];
+      } else {
+        process.env['CLEO_ROOT'] = savedRoot;
+      }
     }
   });
 });