@claude-flow/cli 3.34.0 → 3.35.0

package/.claude/.proven-config-version

@@ -0,0 +1 @@
+sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.32.29
+3.35.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.34.0",
+    "version": "3.35.0",
     "files": {
       "auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
       "hook-handler.cjs": "dae295fb9ae2626b89899c19a20cc911541af82b52d2eeb9b214d618b96e9a86",
@@ -8,6 +8,6 @@
       "statusline.cjs": "0457fe53f8cd2c56458ff178392536a5868efd1a573665fa43bc01d2d95ca677"
     }
   },
-  "signature": "GyTvYvhL7vIta/4yyz1rIyl+DWJ+x4dJVfmcrKZJXlh4E/TcQK2bszRznlaG1o7LWSZTudaYj50w+/7dlv6lDg==",
+  "signature": "tnK2I0enYGI5ql364QJqnAUHMo+pIh0AZK4y/Rad9H+WuPo/KzzG4jqL8/083EbEKWLPEneN6n9s0pEQcGzVCw==",
   "algorithm": "ed25519"
 }

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1785208363552,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 4,
-  "generatedAt": "2026-07-31T15:55:49.000Z",
-  "gitSha": "4ac1ab9f",
+  "generatedAt": "2026-08-10T14:19:13.896Z",
+  "gitSha": "4af1cfdd",
   "catalog": {
     "agents": 164,
     "tools": 397,

package/dist/src/commands/daemon.js

@@ -4,6 +4,7 @@
  */
 import { output } from '../output.js';
 import { getDaemon, startDaemon, stopDaemon } from '../services/worker-daemon.js';
+import { resolveDaemonProjectRoot } from '../services/daemon-autostart.js';
 import { fork } from 'child_process';
 import { fileURLToPath } from 'url';
 import { dirname, join, resolve } from 'path';
@@ -61,7 +62,11 @@ const startCommand = {
         }
         // #1914: a forked daemon child receives --workspace <root>; the launcher
         // and interactive invocations have no flag and fall back to cwd.
-        const projectRoot = resolveWorkspaceFlag(ctx.flags.workspace) ?? process.cwd();
+        // #2877: that cwd fallback is normalized to the owning project root, so
+        // `daemon start` from a subdirectory contends for the SAME lock/PID file
+        // as one from the root instead of silently keying its own pair.
+        const projectRoot = resolveWorkspaceFlag(ctx.flags.workspace)
+            ?? resolveDaemonProjectRoot(process.cwd());
         const isDaemonProcess = process.env.CLAUDE_FLOW_DAEMON === '1';
         // Parse resource threshold overrides from CLI flags
         const config = {};
@@ -605,7 +610,7 @@ const stopCommand = {
     ],
     action: async (ctx) => {
         const quiet = ctx.flags.quiet;
-        const projectRoot = process.cwd();
+        const projectRoot = resolveDaemonProjectRoot(process.cwd());
         // #2661: `stop --all` — the containment lever for daemon fanout across
         // Git worktrees. Only processes positively identified as ruflo daemons
         // (via their self-identifying argv) are touched; each receives SIGTERM
@@ -657,7 +662,7 @@ async function stopAllDaemons(quiet) {
         await stopDaemon();
     }
     catch { /* not running in-process */ }
-    await killBackgroundDaemon(process.cwd());
+    await killBackgroundDaemon(resolveDaemonProjectRoot(process.cwd()));
     const daemons = await scanRunningDaemons();
     if (daemons.length === 0) {
         if (!quiet) {
@@ -1160,7 +1165,7 @@ const statusCommand = {
         if (ctx.flags.all) {
             return renderAllDaemonsStatus();
         }
-        const projectRoot = process.cwd();
+        const projectRoot = resolveDaemonProjectRoot(process.cwd());
         try {
             const daemon = getDaemon(projectRoot);
             const status = daemon.getStatus();
@@ -1304,7 +1309,7 @@ const triggerCommand = {
             // #2661: an explicit `trigger --headless` is user consent for AI
             // execution of THIS run (still governed by the global AI budget).
             // Without the flag, config.json / env opt-in still applies.
-            const daemon = getDaemon(process.cwd(), ctx.flags.headless === true ? { aiWorkersEnabled: true } : undefined);
+            const daemon = getDaemon(resolveDaemonProjectRoot(process.cwd()), ctx.flags.headless === true ? { aiWorkersEnabled: true } : undefined);
             const spinner = output.createSpinner({ text: `Running ${workerType} worker...`, spinner: 'dots' });
             spinner.start();
             const result = await daemon.triggerWorker(workerType);
@@ -1347,7 +1352,7 @@ const enableCommand = {
             return { success: false, exitCode: 1 };
         }
         try {
-            const daemon = getDaemon(process.cwd());
+            const daemon = getDaemon(resolveDaemonProjectRoot(process.cwd()));
             daemon.setWorkerEnabled(workerType, !disable);
             output.printSuccess(`Worker ${workerType} ${disable ? 'disabled' : 'enabled'}`);
             return { success: true };
@@ -1402,7 +1407,7 @@ const installSupervisorCommand = {
         const force = ctx.flags.force === true;
         const load = ctx.flags.load !== false;
         const dryRun = ctx.flags['dry-run'] === true || ctx.flags.dryRun === true;
-        const projectRoot = process.cwd();
+        const projectRoot = resolveDaemonProjectRoot(process.cwd());
         const platform = process.platform;
         if (platform === 'win32') {
             output.printError('Windows scheduled-task installer is not yet implemented.');

package/dist/src/commands/doctor.js

@@ -1766,6 +1766,76 @@ async function checkMetaharnessIntegration() {
         };
     }
 }
+/**
+ * Dependency-contract check: every `@metaharness/*` package this CLI DECLARES
+ * in its own optionalDependencies must actually resolve at runtime. Declared
+ * packages are advertised integration surfaces (`ruflo metaharness evolve`,
+ * flywheel receipt interop, radio coordination) — a declared-but-absent
+ * package means the install dropped an optional dep (or the declaration
+ * regressed to peer-only), so the advertised integration silently degrades.
+ * That is a FAIL, not a warn: warn is reserved for surfaces that were never
+ * advertised as installed (the `npx metaharness` umbrella path above).
+ */
+async function checkMetaharnessDeclaredPackages() {
+    const NAME = 'MetaHarness declared packages (ADR-150)';
+    try {
+        // Walk up from this module to the CLI package root (works for npx cache,
+        // global install, project-local install, and monorepo dev alike).
+        let root = null;
+        let q = dirname(fileURLToPath(import.meta.url));
+        for (let i = 0; i < 8; i++) {
+            const pj = join(q, 'package.json');
+            if (existsSync(pj)) {
+                try {
+                    if (JSON.parse(readFileSync(pj, 'utf-8')).name === '@claude-flow/cli') {
+                        root = q;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+            }
+            q = dirname(q);
+        }
+        if (!root)
+            return { name: NAME, status: 'warn', message: 'could not locate the @claude-flow/cli package root' };
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'));
+        const declared = Object.keys(pkg.optionalDependencies ?? {}).filter((n) => n === 'metaharness' || n.startsWith('@metaharness/'));
+        if (declared.length === 0) {
+            return {
+                name: NAME,
+                status: 'fail',
+                message: 'no @metaharness/* packages declared in optionalDependencies — the dependency contract regressed (peer-only declarations are never installed)',
+                fix: 'Restore @metaharness/darwin, @metaharness/flywheel, @metaharness/radio to optionalDependencies in @claude-flow/cli',
+            };
+        }
+        // Node resolution: nearest node_modules wins, walking upward from the CLI root.
+        const resolves = (name) => {
+            let d = root;
+            for (let i = 0; i < 10; i++) {
+                if (existsSync(join(d, 'node_modules', name, 'package.json')))
+                    return true;
+                const parent = dirname(d);
+                if (parent === d)
+                    break;
+                d = parent;
+            }
+            return false;
+        };
+        const missing = declared.filter((n) => !resolves(n));
+        if (missing.length > 0) {
+            return {
+                name: NAME,
+                status: 'fail',
+                message: `declared but not installed: ${missing.join(', ')} — advertised MetaHarness surfaces are degraded`,
+                fix: 'npm install --include=optional  # optional deps were skipped or pruned',
+            };
+        }
+        return { name: NAME, status: 'pass', message: `${declared.length} declared package(s) resolve: ${declared.join(', ')}` };
+    }
+    catch (err) {
+        return { name: NAME, status: 'warn', message: `check failed: ${err instanceof Error ? err.message : String(err)}` };
+    }
+}
 async function checkMetaharness() {
     try {
         const version = await runCommand('npx -y metaharness@latest --version 2>&1', 15000);
@@ -2116,6 +2186,7 @@ export const doctorCommand = {
             checkEncryptionAtRest, // ADR-096 Phase 5
             checkFederationBreaker, // ADR-097 Phase 4
             checkMetaharness, // ADR-150 — MetaHarness upstream package
+            checkMetaharnessDeclaredPackages, // dependency contract — declared optional deps must resolve
             checkMetaharnessIntegration, // iter 45 — ruflo-side integration layer
             checkFunnel, // ADR-305 — effective funnel state + deciding precedence source
             checkProxySponsoredConsent, // ADR-313 — Meta LLM Proxy sponsored-downtime health
@@ -2158,7 +2229,7 @@ export const doctorCommand = {
             'agentic-flow': checkAgenticFlow,
             'encryption': checkEncryptionAtRest, // ADR-096 Phase 5
             'federation': checkFederationBreaker, // ADR-097 Phase 4
-            'metaharness': checkMetaharness, // ADR-150 — upstream package
+            'metaharness': [checkMetaharness, checkMetaharnessDeclaredPackages, checkMetaharnessIntegration], // ADR-150 — upstream + declared deps + ruflo-side
             'metaharness-integration': checkMetaharnessIntegration, // iter 45 — ruflo-side
             'funnel': checkFunnel, // ADR-305
             // ADR-307 — deep-dive array, same pattern as 'memory' above: the cheap

package/dist/src/commands/metaharness.js

@@ -39,7 +39,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { runFlywheelWorker } from '../services/harness-flywheel-runtime.js';
-import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
+import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, resetSequentialEvidence, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
 import { evaluatePolicyRequest } from '../services/policy-runtime.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // Subcommand → plugin script filename
@@ -124,6 +124,37 @@ async function dispatchFlywheel(operation, positional, flags) {
         const state = readFlywheelTransactionState(projectRoot);
         data = { ledgerHead: state.ledgerHead, commits: state.commits };
     }
+    else if (operation === 'evidence-reset') {
+        // ADR-381 §2 — start a new evidence epoch. Same policy gate as promote:
+        // this reopens the family-wise alpha budget, so it is a governance action.
+        const reason = String(flywheelFlag(flags, 'reason', '')).trim();
+        if (!reason) {
+            data = { success: false, reason: 'evidence-reset requires --reason "<why>" — the reset audit trail records intent' };
+        }
+        else {
+            const policy = await evaluatePolicyRequest({
+                identity: { id: process.env.CLAUDE_FLOW_PRINCIPAL_ID ?? 'metaharness-local', type: 'agent', roles: ['optimizer'] },
+                action: {
+                    type: 'metaharness.evidence.reset',
+                    resource: projectRoot,
+                    environment: 'production',
+                    destructive: true,
+                },
+                context: {
+                    approvalIds: String(flywheelFlag(flags, 'approvalId', '')).split(',').filter(Boolean),
+                },
+            }, projectRoot);
+            if (policy.enforcedOutcome !== 'allowed') {
+                data = { success: false, reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId };
+            }
+            else {
+                data = await resetSequentialEvidence(projectRoot, {
+                    confirm: flywheelFlag(flags, 'confirm', false) === true,
+                    reason,
+                });
+            }
+        }
+    }
     else if (operation === 'promote') {
         const receiptId = positional[0];
         const publicKeyPath = flywheelFlag(flags, 'publicKey');
@@ -151,6 +182,10 @@ async function dispatchFlywheel(operation, positional, flags) {
                 data = await promoteFlywheelCandidate(projectRoot, receiptId, {
                     confirm: flywheelFlag(flags, 'confirm', false) === true,
                     trustedPublicKeys: new Set([publicKey]),
+                    // --allow-aggregate-evidence: explicit migration escape hatch for
+                    // pre-upgrade receipts without task-level pairedOutcomes. Default
+                    // is strict — aggregate-only evidence is refused.
+                    requirePairedEvidence: flywheelFlag(flags, 'allowAggregateEvidence', false) !== true,
                 });
             }
         }
@@ -288,7 +323,7 @@ export const metaharnessCommand = {
             output.writeln('  redblue       adversarial red/blue LLM testing (init|run|patch|attack|report)');
             output.writeln('  evolve        Darwin candidate evolution');
             output.writeln('  bench         create or verify a stable benchmark suite');
-            output.writeln('  flywheel      receipt loop: run | status | receipts | history | promote');
+            output.writeln('  flywheel      receipt loop: run | status | receipts | history | promote | evidence-reset');
             output.writeln('');
             output.writeln('Each subcommand accepts --format json|table and --help.');
             output.writeln('');

package/dist/src/log-filters.d.ts

@@ -40,7 +40,7 @@ declare const STDERR_REDIRECT_PREFIXES: string[];
 declare const AGENTDB_MOCK_FALLBACK_DROP_PREFIXES: string[];
 declare const shouldRedirectToStderr: (msg: unknown) => boolean;
 declare const isAgentdbMockFallbackNoise: (msg: unknown) => boolean;
-declare const origWarn: (message?: any, ...optionalParams: any[]) => void;
-declare const origLog: (message?: any, ...optionalParams: any[]) => void;
-declare const origError: (message?: any, ...optionalParams: any[]) => void;
+declare const origWarn: (...data: any[]) => void;
+declare const origLog: (...data: any[]) => void;
+declare const origError: (...data: any[]) => void;
 //# sourceMappingURL=log-filters.d.ts.map

package/dist/src/mcp-tools/metaharness-tools.js

@@ -53,7 +53,7 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { runFlywheelWorker } from '../services/harness-flywheel-runtime.js';
 import { evaluatePolicyRequest } from '../services/policy-runtime.js';
-import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
+import { listFlywheelReceipts, promoteFlywheelCandidate, readFlywheelTransactionState, resetSequentialEvidence, verifyFlywheelLedger, } from '../services/flywheel-transaction.js';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 /**
  * Walk up from this module to find plugins/ruflo-metaharness/scripts/.
@@ -690,7 +690,7 @@ export const metaharnessTools = [
         inputSchema: {
             type: 'object',
             properties: {
-                operation: { type: 'string', enum: ['run', 'status', 'receipts', 'history', 'promote'], description: 'Flywheel operation', default: 'status' },
+                operation: { type: 'string', enum: ['run', 'status', 'receipts', 'history', 'promote', 'evidence-reset'], description: 'Flywheel operation', default: 'status' },
                 projectRoot: { type: 'string', description: 'Target project root (default: active project cwd)' },
                 receiptId: { type: 'string', description: 'Receipt content ID for promote' },
                 sample: { type: 'number', description: 'Maximum harvested evaluation sample', default: 40 },
@@ -704,6 +704,8 @@ export const metaharnessTools = [
                 anchorHash: { type: 'string', description: 'Pinned sha256 of canonical anchor tasks; requires anchorPath' },
                 anchorManifestPath: { type: 'string', description: 'Project-contained anchor manifest path (default .claude/eval/flywheel-anchor.manifest.json)' },
                 approvalIds: { type: 'array', items: { type: 'string' }, description: 'Scoped ADR-324 approval IDs for privileged promotion' },
+                allowAggregateEvidence: { type: 'boolean', description: 'Migration escape hatch: accept a pre-upgrade receipt without task-level pairedOutcomes. Default false — aggregate-only evidence is refused by the strict sequential-evidence gate.', default: false },
+                reason: { type: 'string', description: 'Required for evidence-reset (ADR-381): the human intent recorded in the append-only reset audit trail.' },
             },
             required: ['operation'],
         },
@@ -758,6 +760,36 @@ export const metaharnessTools = [
                 });
                 return { success: data.ran, data, degraded: false, exitCode: data.ran ? 0 : 1 };
             }
+            if (operation === 'evidence-reset') {
+                // ADR-381 §2 — reopens the family-wise alpha budget; same policy
+                // gate as promote, plus a mandatory recorded reason.
+                const reason = String(input.reason ?? '').trim();
+                if (!reason) {
+                    return { success: false, data: { reason: 'evidence-reset requires a non-empty reason — the reset audit trail records intent' }, degraded: false, exitCode: 2 };
+                }
+                const policy = await evaluatePolicyRequest({
+                    identity: { id: 'metaharness-mcp', type: 'agent', roles: ['optimizer'] },
+                    action: {
+                        type: 'metaharness.evidence.reset',
+                        resource: projectRoot,
+                        environment: 'production',
+                        destructive: true,
+                    },
+                    context: {
+                        approvalIds: Array.isArray(input.approvalIds) ? input.approvalIds.map(String) : undefined,
+                    },
+                }, projectRoot);
+                if (policy.enforcedOutcome !== 'allowed') {
+                    return {
+                        success: false,
+                        data: { reason: `policy-${policy.enforcedOutcome}:${policy.reason}`, policyReceiptId: policy.receiptId },
+                        degraded: false,
+                        exitCode: 1,
+                    };
+                }
+                const data = await resetSequentialEvidence(projectRoot, { confirm: input.confirm === true, reason });
+                return { success: data.success, data, degraded: false, exitCode: data.success ? 0 : 1 };
+            }
             if (operation === 'promote') {
                 if (!input.receiptId || !input.publicKeyPath) {
                     return { success: false, data: { reason: 'receiptId and publicKeyPath are required' }, degraded: false, exitCode: 2 };
@@ -786,6 +818,7 @@ export const metaharnessTools = [
                 const data = await promoteFlywheelCandidate(projectRoot, String(input.receiptId), {
                     confirm: input.confirm === true,
                     trustedPublicKeys: new Set([publicKey]),
+                    requirePairedEvidence: input.allowAggregateEvidence !== true,
                 });
                 return { success: data.success, data, degraded: false, exitCode: data.success ? 0 : 1 };
             }

package/dist/src/memory/memory-bridge.d.ts

@@ -487,6 +487,14 @@ export declare function bridgeHealthCheck(dbPath?: string): Promise<{
         hits: number;
         misses: number;
     };
+    hierarchicalMemory?: {
+        controller: string;
+        durable: boolean;
+        persistence: string;
+        /** Real row count in the backing table — null when nothing is on disk. */
+        persistedRows: number | null;
+        fallbackFrom?: string;
+    };
 } | null>;
 /**
  * Store to hierarchical memory with tier.
@@ -506,6 +514,23 @@ export declare function bridgeHealthCheck(dbPath?: string): Promise<{
  *   temporal fields are stored in metadata, and supersede is reported as
  *   unsupported (no public update API) rather than silently dropped.
  */
+/**
+ * Describe which store `agentdb_hierarchical-*` actually landed on and
+ * whether its writes survive the process (#2887).
+ *
+ * agentdb removed its `HierarchicalMemory` export at 3.0.0-alpha.17, so the
+ * @claude-flow/memory TieredMemoryStore fallback is the live path. It is only
+ * durable when it was handed a SQLite connection — callers must not report a
+ * volatile write as a success.
+ */
+export declare function describeHierarchicalStore(hm: any, fallback: {
+    reason: string;
+} | null): {
+    controller: string;
+    fallbackFrom?: string;
+    durable: boolean;
+    persistence: string;
+};
 export declare function bridgeHierarchicalStore(params: {
     key: string;
     value: string;

package/dist/src/memory/memory-bridge.js

@@ -2392,7 +2392,18 @@ export async function bridgeHealthCheck(dbPath) {
             const s = cache.stats();
             cacheStats = { size: s.size ?? 0, hits: s.hits ?? 0, misses: s.misses ?? 0 };
         }
-        return { available: true, controllers, attestationCount, cacheStats };
+        // #2887: cacheStats alone let a "successful" hierarchical-store coexist
+        // with an empty store. Report the backing table's real row count so the
+        // inconsistency is visible instead of inferred.
+        let hierarchicalMemory;
+        const hm = registry.get('hierarchicalMemory');
+        if (hm) {
+            hierarchicalMemory = {
+                ...describeHierarchicalStore(hm, getHierarchicalFallback(registry)),
+                persistedRows: typeof hm.countPersisted === 'function' ? hm.countPersisted() : null,
+            };
+        }
+        return { available: true, controllers, attestationCount, cacheStats, hierarchicalMemory };
     }
     catch {
         return null;
@@ -2417,6 +2428,34 @@ export async function bridgeHealthCheck(dbPath) {
  *   temporal fields are stored in metadata, and supersede is reported as
  *   unsupported (no public update API) rather than silently dropped.
  */
+/**
+ * Describe which store `agentdb_hierarchical-*` actually landed on and
+ * whether its writes survive the process (#2887).
+ *
+ * agentdb removed its `HierarchicalMemory` export at 3.0.0-alpha.17, so the
+ * @claude-flow/memory TieredMemoryStore fallback is the live path. It is only
+ * durable when it was handed a SQLite connection — callers must not report a
+ * volatile write as a success.
+ */
+export function describeHierarchicalStore(hm, fallback) {
+    // Only the tiered fallback exposes isDurable(); the native controller
+    // (should agentdb reintroduce it) writes to agentdb's own tables.
+    if (typeof hm?.isDurable !== 'function') {
+        return { controller: 'hierarchicalMemory', durable: true, persistence: 'agentdb' };
+    }
+    return {
+        controller: 'tieredMemoryStore',
+        fallbackFrom: fallback?.reason ?? 'hierarchicalMemory',
+        durable: hm.isDurable() === true,
+        persistence: typeof hm.getPersistence === 'function' ? hm.getPersistence() : 'unknown',
+    };
+}
+/** Read `getHierarchicalFallback()` off a registry that may predate it. */
+function getHierarchicalFallback(registry) {
+    return typeof registry?.getHierarchicalFallback === 'function'
+        ? registry.getHierarchicalFallback()
+        : null;
+}
 export async function bridgeHierarchicalStore(params) {
     const registry = await getRegistry();
     if (!registry)
@@ -2439,7 +2478,10 @@ export async function bridgeHierarchicalStore(params) {
                 metadata,
                 tags: [params.key],
             });
-            const result = { success: true, id, key: params.key, tier };
+            const result = {
+                success: true, id, key: params.key, tier,
+                controller: 'hierarchicalMemory', durable: true, persistence: 'agentdb',
+            };
             if (params.supersedes) {
                 // No public update/invalidate API on agentdb HierarchicalMemory —
                 // surface the limitation honestly instead of silently dropping it.
@@ -2448,17 +2490,28 @@ export async function bridgeHierarchicalStore(params) {
             }
             return result;
         }
-        // TieredMemoryStore fallback (temporal-aware) / legacy stub
+        // TieredMemoryStore fallback (temporal-aware) / legacy stub.
+        // agentdb dropped its HierarchicalMemory export at 3.0.0-alpha.17, so
+        // this is the live path — and it is only trustworthy when the store is
+        // backed by SQLite. A volatile write must NOT report success (#2887).
         const storeResult = hm.store(params.key, params.value, tier, {
             validFrom: params.validFrom,
             validUntil: params.validUntil,
             supersedes: params.supersedes,
         });
-        if (storeResult && typeof storeResult === 'object') {
-            return { success: true, ...storeResult };
+        const info = describeHierarchicalStore(hm, getHierarchicalFallback(registry));
+        const base = {
+            ...info,
+            ...(storeResult && typeof storeResult === 'object' ? storeResult : { key: params.key, tier }),
+        };
+        if (!info.durable) {
+            return {
+                ...base,
+                success: false,
+                error: `hierarchical-store is running on the ${info.persistence} tiered fallback (${info.fallbackFrom}); the entry is NOT persisted to disk and will be lost when this process exits. Use memory_store for durable key-value persistence.`,
+            };
         }
-        // Legacy stub (returns void) — temporal options were ignored
-        return { success: true, key: params.key, tier };
+        return { success: true, ...base };
     }
     catch (e) {
         return { success: false, error: e.message };
@@ -2523,7 +2576,7 @@ export async function bridgeHierarchicalRecall(params) {
         const filtered = params.tier
             ? results.filter((r) => r.tier === params.tier)
             : results;
-        return { results: filtered, controller: 'hierarchicalMemory' };
+        return { results: filtered, ...describeHierarchicalStore(hm, getHierarchicalFallback(registry)) };
     }
     catch (e) {
         return { results: [], error: e.message };

package/dist/src/memory/memory-initializer.d.ts

@@ -547,9 +547,15 @@ export declare function deleteEntry(options: {
 }>;
 /**
  * Advisory O_EXCL lock scoped to a single memory.db file (`<dbPath>.lock`),
- * same stale-takeover pattern as services/global-ai-budget.ts. Only
- * meaningful between callers that opt into it (purgeNamespace does); it
- * cannot coordinate against writers that don't call this helper.
+ * same stale-takeover pattern as services/global-ai-budget.ts.
+ *
+ * #2878: sql.js persists by rewriting the whole database image, so every
+ * `load → mutate → export → write` sequence is a read-modify-write that a
+ * concurrent writer can clobber — both callers report success and the loser's
+ * rows vanish, with `PRAGMA integrity_check` still clean. Every such sequence
+ * in this module now runs inside this lock. It is advisory, so it still
+ * cannot coordinate against a writer that bypasses this module entirely
+ * (a native WAL connection — see hasNativeWalSidecars).
  */
 export declare function withMemoryDbLock<T>(dbPath: string, fn: () => Promise<T> | T): Promise<T>;
 export declare function purgeNamespace(options: {