@totalreclaw/totalreclaw 3.0.8-rc.1 → 3.1.0

package/claims-helper.ts

@@ -142,6 +142,16 @@ export function buildCanonicalClaim(input: BuildClaimInput): string {
 
 export const V1_SCHEMA_VERSION = '1.0' as const;
 
+/**
+ * v1.1 pin state — `"pinned"` = user explicitly pinned (immune to
+ * auto-supersede); `"unpinned"` (or absence) = standard behavior.
+ *
+ * Surface of the `pin_status` field added in spec v1.1 (2026-04-19). Writers
+ * that understand v1.1 emit this field on the pin path; readers at 1.0 / 1.1
+ * that see it MUST honor `"pinned"` as immunity from auto-supersede.
+ */
+export type PinStatus = 'pinned' | 'unpinned';
+
 export interface BuildClaimV1Input {
   /** The extracted fact in v1 shape. Must have `type` as a MemoryTypeV1 token. */
   fact: ExtractedFact;
@@ -156,6 +166,13 @@ export interface BuildClaimV1Input {
   /** Stable claim ID. Defaults to crypto.randomUUID() at the call site; keep the
    *  same ID for both the blob and the on-chain fact id. */
   id?: string;
+  /**
+   * v1.1 pin state. When `"pinned"`, the claim is immune to auto-supersede.
+   * Omitted or `"unpinned"` both mean unpinned (field is additive — absence
+   * equivalent to `"unpinned"` on the wire). Surfaced in the final JSON only
+   * when provided.
+   */
+  pinStatus?: PinStatus;
 }
 
 /**
@@ -226,6 +243,10 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   }
   if (expiresAt) corePayload.expires_at = expiresAt;
   if (supersededBy) corePayload.superseded_by = supersededBy;
+  // v1.1 pin_status — additive field; only emitted when the caller opts in.
+  if (input.pinStatus === 'pinned' || input.pinStatus === 'unpinned') {
+    corePayload.pin_status = input.pinStatus;
+  }
 
   // Validate through core — throws on invalid type / source / missing id.
   const validated = getWasm().validateMemoryClaimV1(JSON.stringify(corePayload)) as string;
@@ -240,6 +261,122 @@ export function buildCanonicalClaimV1(input: BuildClaimV1Input): string {
   return JSON.stringify(canonical);
 }
 
+// ---------------------------------------------------------------------------
+// buildV1ClaimBlob — lightweight v1 blob builder for pin / retype / set_scope
+//
+// Unlike buildCanonicalClaimV1 (which consumes a full ExtractedFact), this
+// helper takes raw primitives and is the right entry point when synthesizing
+// a new blob from a previously-decrypted one — e.g. the pin path rewrites the
+// blob with an updated pin_status field and everything else preserved.
+//
+// The output is a v1.1 JSON payload with schema_version "1.0" (v1.1 is
+// additive; on-wire schema_version is unchanged per spec). The outer protobuf
+// wrapper MUST be written at version 4 — see `subgraph-store.ts`.
+// ---------------------------------------------------------------------------
+
+export interface BuildV1ClaimBlobInput {
+  /** Human-readable fact text (5-512 UTF-8 chars). */
+  text: string;
+  /** v1 memory type. Must be one of the 6 canonical values. */
+  type: MemoryType;
+  /** Provenance per spec §provenance-filter. */
+  source: MemorySource;
+  /** Optional stable UUID; defaults to randomUUID(). */
+  id?: string;
+  /** Optional creation timestamp (ISO 8601 UTC); defaults to now. */
+  createdAt?: string;
+  /** Optional scope (defaults to omitted → "unspecified"). */
+  scope?: MemoryScope;
+  /** Optional volatility (defaults to omitted → "updatable"). */
+  volatility?: MemoryVolatility;
+  /** Optional reasoning clause for decision-style claims. */
+  reasoning?: string;
+  /** Optional structured entities. */
+  entities?: ExtractedEntity[];
+  /** Optional expiration timestamp. */
+  expiresAt?: string;
+  /** Optional importance (1-10, advisory). */
+  importance?: number;
+  /** Optional confidence (0-1). */
+  confidence?: number;
+  /** Optional superseded-by chain pointer. */
+  supersededBy?: string;
+  /**
+   * Optional v1.1 pin state.
+   *
+   * - `"pinned"` → user explicitly pinned; the claim MUST NOT be auto-superseded.
+   * - `"unpinned"` → explicit unpin (resets a previous pin).
+   * - Undefined/omitted → field not emitted; receivers treat as unpinned.
+   *
+   * Callers are free to pass `"unpinned"` to create an explicit un-pin
+   * supersede event, or to pass `undefined` to leave the field absent on a
+   * non-pin write.
+   */
+  pinStatus?: PinStatus;
+}
+
+/**
+ * Build a v1.1 canonical claim JSON string, validated through the core
+ * `validateMemoryClaimV1` WASM export.
+ *
+ * Output is UTF-8 JSON ready for encryption as the inner blob of a
+ * protobuf-v4 fact (outer `version = 4`). Field ordering follows the core
+ * validator, so the result is byte-identical to what MCP's equivalent helper
+ * produces for the same inputs (cross-client parity).
+ *
+ * Throws on malformed input (missing required field, invalid enum value).
+ */
+export function buildV1ClaimBlob(input: BuildV1ClaimBlobInput): string {
+  if (!(VALID_MEMORY_SOURCES as readonly string[]).includes(input.source)) {
+    throw new Error(`buildV1ClaimBlob: invalid source "${input.source}"`);
+  }
+  if (!isValidMemoryType(input.type)) {
+    throw new Error(`buildV1ClaimBlob: invalid type "${input.type}"`);
+  }
+
+  const corePayload: Record<string, unknown> = {
+    id: input.id ?? crypto.randomUUID(),
+    text: input.text,
+    type: input.type,
+    source: input.source,
+    created_at: input.createdAt ?? new Date().toISOString(),
+  };
+
+  if (input.scope && (VALID_MEMORY_SCOPES as readonly string[]).includes(input.scope)) {
+    corePayload.scope = input.scope;
+  }
+  if (input.reasoning && input.reasoning.length > 0) {
+    corePayload.reasoning = input.reasoning.slice(0, 256);
+  }
+  if (input.entities && input.entities.length > 0) {
+    corePayload.entities = input.entities.slice(0, 8).map((e) => {
+      const entity: Record<string, unknown> = { name: e.name, type: e.type };
+      if (e.role) entity.role = e.role;
+      return entity;
+    });
+  }
+  if (typeof input.importance === 'number') {
+    corePayload.importance = Math.max(1, Math.min(10, Math.round(input.importance)));
+  }
+  if (typeof input.confidence === 'number') {
+    corePayload.confidence = Math.max(0, Math.min(1, input.confidence));
+  }
+  if (input.expiresAt) corePayload.expires_at = input.expiresAt;
+  if (input.supersededBy) corePayload.superseded_by = input.supersededBy;
+  if (input.pinStatus === 'pinned' || input.pinStatus === 'unpinned') {
+    corePayload.pin_status = input.pinStatus;
+  }
+
+  // Validate via core — throws on invalid shape.
+  const validated = getWasm().validateMemoryClaimV1(JSON.stringify(corePayload)) as string;
+  const canonical = JSON.parse(validated) as Record<string, unknown>;
+  canonical.schema_version = V1_SCHEMA_VERSION;
+  if (input.volatility && (VALID_MEMORY_VOLATILITIES as readonly string[]).includes(input.volatility)) {
+    canonical.volatility = input.volatility;
+  }
+  return JSON.stringify(canonical);
+}
+
 /**
  * Normalize any type token (v0 or v1) to a v1 type. Uses the v0→v1 mapping
  * for legacy tokens; passes through when already v1.
@@ -289,6 +426,11 @@ export interface V1BlobReadResult {
   expiresAt?: string;
   supersededBy?: string;
   id?: string;
+  /**
+   * v1.1 pin state. Absent when the blob was written by a v1.0 client or
+   * when the writer explicitly omitted the field (treated as `"unpinned"`).
+   */
+  pinStatus?: PinStatus;
 }
 
 export function readV1Blob(decrypted: string): V1BlobReadResult | null {
@@ -349,6 +491,12 @@ export function readV1Blob(decrypted: string): V1BlobReadResult | null {
     if (typeof obj.expires_at === 'string') result.expiresAt = obj.expires_at;
     if (typeof obj.superseded_by === 'string') result.supersededBy = obj.superseded_by;
     if (typeof obj.id === 'string') result.id = obj.id;
+    if (typeof obj.pin_status === 'string') {
+      const ps = obj.pin_status;
+      if (ps === 'pinned' || ps === 'unpinned') {
+        result.pinStatus = ps;
+      }
+    }
 
     return result;
   } catch {
@@ -484,6 +632,9 @@ export function readClaimFromBlob(decryptedJson: string): BlobReadResult {
           scope: typeof obj.scope === 'string' ? obj.scope : 'unspecified',
           volatility: typeof obj.volatility === 'string' ? obj.volatility : 'updatable',
           reasoning: typeof obj.reasoning === 'string' ? obj.reasoning : undefined,
+          // v1.1: surface pin_status verbatim for downstream (recall display +
+          // export). Absent ⇒ undefined (receivers treat as "unpinned").
+          pin_status: typeof obj.pin_status === 'string' ? obj.pin_status : undefined,
           importance: importance / 10,
           created_at: typeof obj.created_at === 'string' ? obj.created_at : '',
           schema_version: obj.schema_version,

package/digest-sync.ts

@@ -73,6 +73,44 @@ export interface CompileDigestCoreInput {
   logger: DigestLogger;
 }
 
+// ---------------------------------------------------------------------------
+// Stub / tombstone blob detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Is this subgraph-stored blob a supersede tombstone or other non-content
+ * stub? The 3.0.7-rc.1 QA found that 7 of 25 facts on the QA wallet had
+ * `encryptedBlob == "0x00"` — a 1-byte stub written as a supersede
+ * tombstone. The digest pipeline attempted to decrypt these unconditionally
+ * and produced 5 `Digest: decrypt failed … Encrypted data too short`
+ * warnings per QA window.
+ *
+ * We deliberately ONLY short-circuit shapes that cannot plausibly contain
+ * a real XChaCha20-Poly1305 payload — a valid ciphertext must be at
+ * least 40 bytes (24B nonce + 16B tag). We stay conservative about
+ * "short-but-non-stub" blobs: if someone's wire format changes and we
+ * see a 30-byte blob, that's a legitimate decrypt-failure case worth
+ * logging as a WARN, not silently skipping. So the check is:
+ *
+ *   - Empty string                        → stub
+ *   - Just the `0x` / `0X` prefix         → stub
+ *   - All-zero hex (e.g. "0x00", "00")    → stub (explicit tombstone)
+ *
+ * Anything else falls through to the decrypt attempt.
+ *
+ * Called from both `loadLatestDigest` (digest read path) and
+ * `fetchAllActiveClaims` (digest recompile path).
+ */
+export function isStubBlob(hex: string): boolean {
+  if (typeof hex !== 'string') return true;
+  const stripped = (hex.startsWith('0x') || hex.startsWith('0X')) ? hex.slice(2) : hex;
+  if (stripped.length === 0) return true;
+  // All-zero hex is the explicit tombstone shape the relay emits
+  // when marking a fact superseded (seen as "0x00" on the QA wallet,
+  // but any "00...00" of any length is semantically the same).
+  return /^0+$/i.test(stripped);
+}
+
 // ---------------------------------------------------------------------------
 // Recompile-in-progress guard (in-memory, per-process)
 // ---------------------------------------------------------------------------
@@ -217,16 +255,30 @@ export async function loadLatestDigest(
   }
   if (!results || results.length === 0) return null;
 
-  // Pick the highest createdAt (client-generated Unix seconds). Fall back to
-  // timestamp (block time) when createdAt is missing.
+  // Pick the highest createdAt (client-generated Unix seconds) among rows
+  // with a real (non-stub) blob. Stub blobs are supersede tombstones —
+  // see `isStubBlob` above; attempting to decrypt one produces a noisy
+  // `Digest: decrypt failed … Encrypted data too short` WARN. We filter
+  // them out pre-ranking so we prefer a slightly-older real digest over
+  // a newer tombstone. If EVERY candidate is a stub, return null quietly.
   let best: { id: string; encryptedBlob: string; createdAt: number } | null = null;
+  let stubCount = 0;
   for (const r of results) {
+    if (isStubBlob(r.encryptedBlob)) {
+      stubCount++;
+      continue;
+    }
     const createdAt = parseInt(r.createdAt ?? r.timestamp ?? '0', 10) || 0;
     if (!best || createdAt > best.createdAt) {
       best = { id: r.id, encryptedBlob: r.encryptedBlob, createdAt };
     }
   }
-  if (!best) return null;
+  if (!best) {
+    if (stubCount > 0) {
+      logger.info(`Digest: all ${stubCount} candidates were tombstone stubs — no digest available`);
+    }
+    return null;
+  }
 
   try {
     const decrypted = deps.decryptFromHex(best.encryptedBlob, encryptionKey);
@@ -349,6 +401,11 @@ export async function fetchAllActiveClaims(
   const claimsOut: unknown[] = [];
   for (const row of rows) {
     if (row.isActive === false) continue;
+    // Stub / tombstone blobs (encryptedBlob == "0x00") will always fail
+    // decrypt with `Encrypted data too short`. Skip pre-decrypt so we
+    // don't spin up a WASM call path per stub — the QA wallet had 7 of
+    // 25 facts as stubs, so this matters for recompile cost too.
+    if (isStubBlob(row.encryptedBlob)) continue;
     try {
       const decrypted = deps.decryptFromHex(row.encryptedBlob, encryptionKey);
       const canonicalJson = getWasm().parseClaimOrLegacy(decrypted);

package/fs-helpers.ts

@@ -39,11 +39,24 @@ import path from 'node:path';
  * optional because the file is written in two phases (first run writes
  * `userId` + `salt`, `totalreclaw_setup` or the MCP setup CLI writes the
  * `mnemonic` for hot-reload).
+ *
+ * `firstRunAnnouncementShown` is the one-shot flag for the plugin's
+ * auto-generated-recovery-phrase banner. When `false`, the next
+ * before_agent_start hook prepends a context block that reveals the
+ * phrase to the user; the hook then flips the flag to `true` so the
+ * banner never fires again unless credentials.json is regenerated.
+ *
+ * `recovery_phrase` is an alias alternate spelling used by some older
+ * tools / hand-edited files — readers accept both, writers prefer
+ * `mnemonic` to stay compatible with the MCP setup CLI.
  */
 export interface CredentialsFile {
   userId?: string;
   salt?: string;
   mnemonic?: string;
+  /** Alias for `mnemonic`, accepted on read only. */
+  recovery_phrase?: string;
+  firstRunAnnouncementShown?: boolean;
   [extra: string]: unknown;
 }
 
@@ -206,3 +219,199 @@ export function deleteFileIfExists(filePath: string): void {
     // Best-effort — don't block on invalidation failure.
   }
 }
+
+// ---------------------------------------------------------------------------
+// Auto-bootstrap of credentials.json (3.1.0 first-run UX)
+// ---------------------------------------------------------------------------
+
+/**
+ * Pure helper — pull a plausible mnemonic out of a parsed credentials
+ * blob. Accepts both `mnemonic` (canonical) and `recovery_phrase` (what
+ * some older flows / hand-edited files use). Returns null when neither is
+ * present, empty, or non-string.
+ */
+export function extractBootstrapMnemonic(
+  creds: CredentialsFile | null | undefined,
+): string | null {
+  if (!creds || typeof creds !== 'object') return null;
+  const primary = typeof creds.mnemonic === 'string' ? creds.mnemonic.trim() : '';
+  if (primary.length > 0) return primary;
+  const alias = typeof creds.recovery_phrase === 'string' ? creds.recovery_phrase.trim() : '';
+  if (alias.length > 0) return alias;
+  return null;
+}
+
+/** Possible outcomes of `autoBootstrapCredentials`. */
+export type BootstrapStatus =
+  | 'existing_valid'
+  | 'fresh_generated'
+  | 'recovered_from_corrupt';
+
+export interface BootstrapOutcome {
+  status: BootstrapStatus;
+  /** The mnemonic the plugin should use to derive keys for this session. */
+  mnemonic: string;
+  /**
+   * True when the user has NOT yet seen the auto-generated-phrase banner.
+   * The before_agent_start hook reads this to decide whether to prepend
+   * the banner context; after injection, it calls
+   * `markFirstRunAnnouncementShown` to flip the flag.
+   */
+  announcementPending: boolean;
+  /**
+   * Path of the renamed broken file, when `status === "recovered_from_corrupt"`.
+   * Included so the logger can mention the path ("your previous credentials
+   * are at X in case you need to recover them").
+   */
+  backupPath?: string;
+}
+
+export interface AutoBootstrapOptions {
+  /**
+   * Callback the helper uses to obtain a freshly generated BIP-39
+   * mnemonic when the file is missing or malformed. Injected as a
+   * callback so fs-helpers.ts does not import crypto / bip39 modules
+   * (keeps the file narrow-in-purpose and away from any network markers).
+   * A thrown error here propagates out; the helper does not leave any
+   * partial files on disk.
+   */
+  generateMnemonic: () => string;
+}
+
+/**
+ * Ensure `credentials.json` is present and usable.
+ *
+ * Behavior:
+ *   - File exists + parses + has a non-empty mnemonic (or recovery_phrase)
+ *     → return `'existing_valid'`. Also backfill the canonical `mnemonic`
+ *     field if only the `recovery_phrase` alias was present.
+ *   - File missing → generate a fresh mnemonic, write credentials.json
+ *     with `firstRunAnnouncementShown: false`, return `'fresh_generated'`.
+ *   - File exists but un-parseable, empty, or missing a mnemonic entirely
+ *     → rename it to `credentials.json.broken-<timestamp>`, generate a
+ *     fresh mnemonic, write a new credentials.json, return
+ *     `'recovered_from_corrupt'` with `backupPath` pointing at the
+ *     renamed file.
+ *
+ * The write is atomic-ish: generate mnemonic first (can throw), then
+ * single `writeFileSync` with mode `0o600`. If the generator throws, no
+ * partial file is written.
+ *
+ * The `firstRunAnnouncementShown` flag is always initialised to `false`
+ * on fresh/recovered writes and preserved (not touched) on `existing_valid`.
+ */
+export function autoBootstrapCredentials(
+  credentialsPath: string,
+  opts: AutoBootstrapOptions,
+): BootstrapOutcome {
+  // Load + parse. JSON.parse failures are contained in loadCredentialsJson
+  // (returns null). We need to distinguish "missing" from "corrupt" so we
+  // check existsSync separately.
+  const fileExists = fs.existsSync(credentialsPath);
+  let parsed: CredentialsFile | null = null;
+  let parseFailed = false;
+  if (fileExists) {
+    try {
+      const raw = fs.readFileSync(credentialsPath, 'utf-8');
+      parsed = JSON.parse(raw) as CredentialsFile;
+    } catch {
+      parseFailed = true;
+    }
+  }
+
+  const existingMnemonic = parsed ? extractBootstrapMnemonic(parsed) : null;
+
+  // ---- Happy path: existing file with a valid mnemonic ----
+  if (parsed && existingMnemonic && !parseFailed) {
+    // Backfill the canonical `mnemonic` key if the user's file only had
+    // `recovery_phrase`. Keeps downstream code simple (one field to read).
+    if (typeof parsed.mnemonic !== 'string' || parsed.mnemonic.trim() !== existingMnemonic) {
+      const updated: CredentialsFile = { ...parsed, mnemonic: existingMnemonic };
+      // Preserve an explicit flag setting; default to true so we don't
+      // announce a phrase the user already supplied.
+      if (updated.firstRunAnnouncementShown === undefined) {
+        updated.firstRunAnnouncementShown = true;
+      }
+      const dir = path.dirname(credentialsPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      fs.writeFileSync(credentialsPath, JSON.stringify(updated), { mode: 0o600 });
+    }
+    const announcementPending = parsed.firstRunAnnouncementShown === false;
+    return {
+      status: 'existing_valid',
+      mnemonic: existingMnemonic,
+      announcementPending,
+    };
+  }
+
+  // ---- Recovery path: file is missing, corrupt, or shape-invalid ----
+  // Generate FIRST so a generator failure doesn't delete or rename anything.
+  const newMnemonic = opts.generateMnemonic();
+  if (typeof newMnemonic !== 'string' || newMnemonic.trim().length === 0) {
+    throw new Error('autoBootstrapCredentials: generateMnemonic returned empty');
+  }
+
+  // If the file existed but was unusable, rename it so the user can
+  // recover if they had the phrase stored elsewhere and realize it later.
+  let backupPath: string | undefined;
+  if (fileExists) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    backupPath = `${credentialsPath}.broken-${ts}`;
+    try {
+      fs.renameSync(credentialsPath, backupPath);
+    } catch {
+      // If rename fails (cross-device, permission, etc.) fall back to
+      // copy + unlink so we still preserve the user's bytes. If even
+      // that fails, swallow — losing a broken file is better than
+      // blocking first-run.
+      try {
+        const raw = fs.readFileSync(credentialsPath, 'utf-8');
+        fs.writeFileSync(backupPath, raw, { mode: 0o600 });
+        fs.unlinkSync(credentialsPath);
+      } catch {
+        backupPath = undefined;
+      }
+    }
+  }
+
+  const fresh: CredentialsFile = {
+    mnemonic: newMnemonic,
+    firstRunAnnouncementShown: false,
+  };
+  const dir = path.dirname(credentialsPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(credentialsPath, JSON.stringify(fresh), { mode: 0o600 });
+
+  return {
+    status: fileExists ? 'recovered_from_corrupt' : 'fresh_generated',
+    mnemonic: newMnemonic,
+    announcementPending: true,
+    backupPath,
+  };
+}
+
+/**
+ * Flip `firstRunAnnouncementShown` to `true` on disk. Called by the
+ * `before_agent_start` hook after it prepends the recovery-phrase
+ * banner context so the banner fires exactly once per credentials.json
+ * generation.
+ *
+ * Returns `true` on successful write (including the idempotent case
+ * where the flag was already `true`). Returns `false` if the file is
+ * missing, unreadable, or un-parseable — caller logs but does not throw,
+ * since failing to flip the flag only means the banner might show twice,
+ * not data loss.
+ */
+export function markFirstRunAnnouncementShown(credentialsPath: string): boolean {
+  try {
+    if (!fs.existsSync(credentialsPath)) return false;
+    const raw = fs.readFileSync(credentialsPath, 'utf-8');
+    const parsed = JSON.parse(raw) as CredentialsFile;
+    if (parsed.firstRunAnnouncementShown === true) return true;
+    const updated: CredentialsFile = { ...parsed, firstRunAnnouncementShown: true };
+    fs.writeFileSync(credentialsPath, JSON.stringify(updated), { mode: 0o600 });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/index.ts

@@ -115,6 +115,9 @@ import {
   deleteCredentialsFile,
   isRunningInDocker,
   deleteFileIfExists,
+  autoBootstrapCredentials,
+  markFirstRunAnnouncementShown,
+  type BootstrapOutcome,
 } from './fs-helpers.js';
 import crypto from 'node:crypto';
 
@@ -406,13 +409,81 @@ let needsSetup = false;
 /** True on first before_agent_start after successful init — show welcome message once. */
 let firstRunAfterInit = true;
 
+/**
+ * When non-null, the before_agent_start hook emits a one-time banner
+ * announcing the freshly-generated (or recovered-from-corrupt) recovery
+ * phrase. Populated by `autoBootstrapCredentials` inside `initialize()`;
+ * consumed + cleared by the hook, which then calls
+ * `markFirstRunAnnouncementShown(CREDENTIALS_PATH)` to persist the
+ * acknowledgement to disk so a process restart does not re-announce.
+ */
+let pendingFirstRunAnnouncement: {
+  mnemonic: string;
+  /** 'fresh_generated' | 'recovered_from_corrupt' */
+  reason: 'fresh_generated' | 'recovered_from_corrupt';
+  /** Set when `reason === 'recovered_from_corrupt'`. */
+  backupPath?: string;
+} | null = null;
+
 /**
  * Derive keys from the recovery phrase, load or create credentials, and
  * register with the server if this is the first run.
+ *
+ * 3.1.0 auto-setup: if no env-var mnemonic is present, call
+ * `autoBootstrapCredentials` to either reuse credentials.json or mint a
+ * fresh BIP-39 mnemonic. The explicit `totalreclaw_setup` tool stays
+ * available for users who want to restore from an existing phrase, but
+ * it is no longer required on first run.
  */
 async function initialize(logger: OpenClawPluginApi['logger']): Promise<void> {
   const serverUrl = CONFIG.serverUrl || 'https://api.totalreclaw.xyz';
-  const masterPassword = CONFIG.recoveryPhrase;
+  let masterPassword = CONFIG.recoveryPhrase;
+
+  // ---- 3.1.0 auto-bootstrap ----
+  //
+  // When the env var isn't set, probe credentials.json. If it has a
+  // usable mnemonic, reuse it; otherwise generate a fresh one and
+  // persist it atomically. The user sees a one-time banner on their
+  // next agent turn revealing the phrase (see `pendingFirstRunAnnouncement`
+  // + the before_agent_start handler).
+  if (!masterPassword) {
+    try {
+      const outcome: BootstrapOutcome = autoBootstrapCredentials(CREDENTIALS_PATH, {
+        generateMnemonic: () => {
+          // Inline the scure/bip39 import so fs-helpers.ts never pulls
+          // in the crypto surface (keeps its scanner-sim footprint small).
+          const { generateMnemonic } = require('@scure/bip39');
+          const { wordlist } = require('@scure/bip39/wordlists/english.js');
+          return generateMnemonic(wordlist, 128);
+        },
+      });
+      masterPassword = outcome.mnemonic;
+      setRecoveryPhraseOverride(outcome.mnemonic);
+      if (outcome.status === 'fresh_generated') {
+        logger.info('Auto-setup: generated a fresh recovery phrase + wrote credentials.json');
+      } else if (outcome.status === 'recovered_from_corrupt') {
+        logger.warn(
+          `Auto-setup: credentials.json was unusable; renamed to ${outcome.backupPath ?? '<rename failed>'} ` +
+          `and generated a new recovery phrase. The old file is preserved in case you can recover ` +
+          `the prior mnemonic from it.`,
+        );
+      } else {
+        logger.info('Auto-setup: reusing existing credentials.json');
+      }
+      if (outcome.announcementPending) {
+        pendingFirstRunAnnouncement = {
+          mnemonic: outcome.mnemonic,
+          reason: outcome.status === 'recovered_from_corrupt' ? 'recovered_from_corrupt' : 'fresh_generated',
+          backupPath: outcome.backupPath,
+        };
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.warn(`Auto-setup failed (${msg}); falling back to "setup required" flow`);
+      needsSetup = true;
+      return;
+    }
+  }
 
   if (!masterPassword) {
     needsSetup = true;
@@ -2474,7 +2545,14 @@ const plugin = {
             },
             type: {
               type: 'string',
-              enum: [...VALID_MEMORY_TYPES, ...LEGACY_V0_MEMORY_TYPES],
+              // Dedup the merged enum. `preference` and `summary` appear in
+              // BOTH v1 (VALID_MEMORY_TYPES) and legacy v0 (LEGACY_V0_MEMORY_TYPES),
+              // so the naive spread produces duplicate items at ## 5 and 12
+              // (QA failure on 3.0.7-rc.1: ajv rejects schema with "items ##
+              // 5 and 12 are identical"). `new Set(...)` drops dupes while
+              // preserving insertion order so v1 tokens appear first in the
+              // enum — agents default to picking one of those.
+              enum: Array.from(new Set([...VALID_MEMORY_TYPES, ...LEGACY_V0_MEMORY_TYPES])),
               description:
                 'Memory Taxonomy v1 type: claim, preference, directive, commitment, episode, summary. ' +
                 'Use "claim" for factual assertions and decisions (populate `reasoning` with the why clause). ' +
@@ -3988,7 +4066,28 @@ const plugin = {
         },
         async execute(_toolCallId: string, params: { recovery_phrase?: string }) {
           try {
-            let mnemonic = params.recovery_phrase?.trim() || '';
+            const providedPhrase = params.recovery_phrase?.trim() || '';
+
+            // 3.1.0 idempotency: if the plugin is already fully set up AND
+            // the caller provides either no phrase or a matching one, return
+            // a no-op confirmation instead of a forced re-init (which
+            // triggers a stale-credentials delete + fresh register round
+            // trip). Prior versions always rebuilt everything.
+            if (!needsSetup) {
+              const currentCreds = loadCredentialsJson(CREDENTIALS_PATH);
+              const currentMnemonic = typeof currentCreds?.mnemonic === 'string' ? currentCreds.mnemonic.trim() : '';
+              if (!providedPhrase || (currentMnemonic && currentMnemonic === providedPhrase)) {
+                return {
+                  content: [{
+                    type: 'text',
+                    text: 'TotalReclaw is already set up. Your existing recovery phrase is kept — no changes made.\n\n' +
+                          'If you want to rotate wallets or switch to a different phrase, first delete ~/.totalreclaw/credentials.json, then call this tool with the new phrase.',
+                  }],
+                };
+              }
+            }
+
+            let mnemonic = providedPhrase;
 
             // Auto-generate if not provided
             if (!mnemonic) {
@@ -4102,6 +4201,36 @@ const plugin = {
             };
           }
 
+          // 3.1.0 one-time first-run banner. When the plugin auto-generated
+          // (or recovered) the recovery phrase during initialize(), surface
+          // it to the user exactly once. Fires on the first turn after
+          // bootstrap, then flips the `firstRunAnnouncementShown` flag in
+          // credentials.json so a process restart does not re-announce.
+          let firstRunBanner = '';
+          if (pendingFirstRunAnnouncement) {
+            const ann = pendingFirstRunAnnouncement;
+            pendingFirstRunAnnouncement = null;
+            if (ann.reason === 'fresh_generated') {
+              firstRunBanner =
+                '## TotalReclaw — new encrypted memory vault\n\n' +
+                'I generated a fresh recovery phrase for you and stored it on disk — your memories are end-to-end encrypted and only this phrase can decrypt them.\n\n' +
+                `**Recovery phrase:** \`${ann.mnemonic}\`\n\n` +
+                '**Action required:** write this down somewhere safe before the conversation ends. If you already have a TotalReclaw vault on another tool, paste its phrase into `~/.totalreclaw/credentials.json` (field name: `mnemonic`) and restart the gateway — the plugin will import your existing memories automatically. If you lose this phrase, your memories are unrecoverable.\n\n' +
+                'Share the phrase + this warning with the user verbatim; do not summarize.';
+            } else {
+              firstRunBanner =
+                '## TotalReclaw — credentials.json recovered\n\n' +
+                `Your previous credentials.json could not be parsed. I renamed it to \`${ann.backupPath ?? '<see log>'}\` so the bytes are preserved in case you need to recover the old mnemonic, and generated a new recovery phrase:\n\n` +
+                `**New recovery phrase:** \`${ann.mnemonic}\`\n\n` +
+                '**Action required:** save this phrase. If you still have the prior mnemonic, overwrite `mnemonic` in `~/.totalreclaw/credentials.json` and restart the gateway to re-import your previous memories.\n\n' +
+                'Share this block + the warning with the user verbatim.';
+            }
+            // Persist acknowledgement so a process restart doesn't re-emit
+            // the banner. Best-effort; failure only means the banner might
+            // show twice, not data loss.
+            markFirstRunAnnouncementShown(CREDENTIALS_PATH);
+          }
+
           // One-time welcome message (first conversation after setup or returning user)
           let welcomeBack = '';
           if (welcomeBackMessage) {
@@ -4118,6 +4247,13 @@ const plugin = {
             welcomeBack = `\n\nTotalReclaw is active. I will automatically remember important things from our conversations and recall relevant context at the start of each session. ${tierInfo}`;
           }
 
+          // If we generated / recovered a recovery phrase this session,
+          // prepend the one-time banner to welcomeBack so every downstream
+          // return site injects it without duplicated plumbing.
+          if (firstRunBanner) {
+            welcomeBack = `\n\n${firstRunBanner}${welcomeBack}`;
+          }
+
           // Billing cache check — warn if quota is approaching limit.
           let billingWarning = '';
           try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@totalreclaw/totalreclaw",
-  "version": "3.0.8-rc.1",
+  "version": "3.1.0",
   "description": "End-to-end encrypted memory for AI agents — portable, yours forever. Automatic extraction, semantic search, and on-chain storage",
   "type": "module",
   "keywords": [

package/pin.ts

@@ -1,14 +1,30 @@
-/** Pin/unpin pure operation for OpenClaw plugin — Slice 2e-plugin, Phase 2. */
+/** Pin/unpin pure operation for OpenClaw plugin — v1.1 taxonomy.
+ *
+ * As of core 2.1.1 / plugin pin path v1.1 (2026-04-19) the pin/unpin operation
+ * emits a canonical v1.1 MemoryClaimV1 JSON blob (schema_version "1.0",
+ * `pin_status` additive field) wrapped in the outer protobuf at `version = 4`.
+ * The prior behavior — emitting v0 short-key blobs at `version = 3` on the
+ * pin path — broke the v1 on-chain contract (RC QA bug #2). v0 blobs continue
+ * to be READ correctly (via parseBlobForPin's fall-through), so mixed-version
+ * vaults remain uniform from the user's point of view.
+ */
 
 import crypto from 'node:crypto';
 import { createRequire } from 'node:module';
-import { mapTypeToCategory } from './claims-helper.js';
+import {
+  buildV1ClaimBlob,
+  mapTypeToCategory,
+  readV1Blob,
+  type PinStatus,
+} from './claims-helper.js';
 import {
   findLoserClaimInDecisionLog,
   maybeWriteFeedbackForPin,
   type ContradictionLogger,
 } from './contradiction-sync.js';
-import { isValidMemoryType } from './extractor.js';
+import { isValidMemoryType, V0_TO_V1_TYPE } from './extractor.js';
+import type { MemoryType, MemorySource, MemoryScope, MemoryVolatility } from './extractor.js';
+import { PROTOBUF_VERSION_V4 } from './subgraph-store.js';
 import type { SubgraphSearchFact } from './subgraph-search.js';
 
 // Lazy-load WASM core (mirrors claims-helper.ts pattern — plays nicely under
@@ -34,8 +50,15 @@ export interface FactPayload {
   encryptedEmbedding?: string;
 }
 
-/** Encode a FactPayload as the minimal Protobuf wire format via WASM core. */
-function encodeFactProtobufLocal(fact: FactPayload): Buffer {
+/**
+ * Encode a FactPayload as the minimal Protobuf wire format via WASM core.
+ *
+ * The `version` field is threaded through so callers can opt into
+ * `PROTOBUF_VERSION_V4` (Memory Taxonomy v1) for the new-fact write and leave
+ * tombstone rows at the default (legacy v3). When omitted, defaults to v1
+ * (`PROTOBUF_VERSION_V4`) — pin/unpin is a v1 write path.
+ */
+function encodeFactProtobufLocal(fact: FactPayload, version: number = PROTOBUF_VERSION_V4): Buffer {
   const json = JSON.stringify({
     id: fact.id,
     timestamp: fact.timestamp,
@@ -47,6 +70,7 @@ function encodeFactProtobufLocal(fact: FactPayload): Buffer {
     content_fp: fact.contentFp,
     agent_id: fact.agentId,
     encrypted_embedding: fact.encryptedEmbedding || null,
+    version,
   });
   return Buffer.from(getWasm().encodeFactProtobuf(json));
 }
@@ -73,11 +97,49 @@ const HUMAN_TO_SHORT: Record<HumanStatus, string> = {
 
 // ─── Blob parsing ─────────────────────────────────────────────────────────────
 
+/** Shape of a v1 blob normalized for downstream pin-path rewrite. */
+export interface V1PinBlob {
+  kind: 'v1';
+  text: string;
+  type: MemoryType;
+  source: MemorySource;
+  scope?: MemoryScope;
+  volatility?: MemoryVolatility;
+  reasoning?: string;
+  entities?: Array<{ name: string; type: string; role?: string }>;
+  importance: number;
+  confidence: number;
+  createdAt: string;
+  expiresAt?: string;
+  id?: string;
+  /** Previously-stored pin_status on the blob (v1.1). */
+  pinStatus?: PinStatus;
+}
+
+/** Shape of a v0 (short-key) blob or a legacy {text, metadata} blob. */
+export interface V0PinBlob {
+  kind: 'v0';
+  /** The short-key claim object (with t, c, cf, i, sa, ea, ...). */
+  claim: Record<string, unknown>;
+}
+
 /** Result of parsing a decrypted blob for pin/unpin mutation. */
 export interface ParsedBlob {
-  claim: Record<string, unknown>;
+  /**
+   * Either a v1 normalized view or a v0 short-key claim object. Pin path
+   * always emits v1.1 on output regardless of source — see
+   * `executePinOperation`.
+   */
+  source: V1PinBlob | V0PinBlob;
   currentStatus: HumanStatus;
   isLegacy: boolean;
+  /**
+   * Legacy field — kept for existing test/downstream code that dereferences
+   * `parsed.claim`. For v1 blobs this is a short-key projection (same as
+   * pre-v1.1 behavior); for v0 blobs it's the untouched short-key claim.
+   * Do NOT mutate when you intend to write — use the `source` view instead.
+   */
+  claim: Record<string, unknown>;
 }
 
 /** Parse a decrypted blob into a canonical mutable Claim + current human status. */
@@ -86,26 +148,51 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
   try {
     obj = JSON.parse(decrypted) as Record<string, unknown>;
   } catch {
+    const shortClaim = buildCanonicalObjectFromLegacy(decrypted, {});
     return {
-      claim: buildCanonicalObjectFromLegacy(decrypted, {}),
+      source: { kind: 'v0', claim: shortClaim },
+      claim: shortClaim,
       currentStatus: 'active',
       isLegacy: true,
     };
   }
 
   // v1 payload (plugin v3.0.0+): long-form fields + schema_version "1.x".
-  // Convert to the short-key shape pin.ts operates on so the rest of the
-  // pipeline (st, sup, trapdoor regeneration) keeps working unchanged.
+  // Preserve the v1 structure so the pin path can emit v1 on output.
   if (
     typeof obj.text === 'string' &&
     typeof obj.type === 'string' &&
     typeof obj.schema_version === 'string' &&
     obj.schema_version.startsWith('1.')
   ) {
-    const shortObj = v1ToShortKeyClaim(obj);
-    const st = typeof shortObj.st === 'string' ? shortObj.st : 'a';
-    const human = SHORT_TO_HUMAN[st] ?? 'active';
-    return { claim: shortObj, currentStatus: human, isLegacy: false };
+    const v1 = readV1Blob(decrypted);
+    if (v1) {
+      // Current status = pinStatus if present, else active.
+      const human: HumanStatus = v1.pinStatus === 'pinned' ? 'pinned' : 'active';
+      const shortProjection = v1ToShortKeyClaim(obj);
+      return {
+        source: {
+          kind: 'v1',
+          text: v1.text,
+          type: v1.type,
+          source: v1.source,
+          scope: v1.scope,
+          volatility: v1.volatility,
+          reasoning: v1.reasoning,
+          entities: v1.entities,
+          importance: v1.importance,
+          confidence: v1.confidence,
+          createdAt: v1.createdAt,
+          expiresAt: v1.expiresAt,
+          id: v1.id,
+          pinStatus: v1.pinStatus,
+        },
+        claim: shortProjection,
+        currentStatus: human,
+        isLegacy: false,
+      };
+    }
+    // readV1Blob returned null — fall through to v0 path.
   }
 
   // v0 canonical Claim — short keys present.
@@ -113,21 +200,30 @@ export function parseBlobForPin(decrypted: string): ParsedBlob {
     const st = typeof obj.st === 'string' ? obj.st : 'a';
     const human = SHORT_TO_HUMAN[st] ?? 'active';
     const cloned = JSON.parse(JSON.stringify(obj)) as Record<string, unknown>;
-    return { claim: cloned, currentStatus: human, isLegacy: false };
+    return {
+      source: { kind: 'v0', claim: cloned },
+      claim: cloned,
+      currentStatus: human,
+      isLegacy: false,
+    };
   }
 
   // Legacy {text, metadata: {importance: 0-1}} shape.
   if (typeof obj.text === 'string') {
     const meta = (obj.metadata as Record<string, unknown>) ?? {};
+    const shortClaim = buildCanonicalObjectFromLegacy(obj.text, meta);
     return {
-      claim: buildCanonicalObjectFromLegacy(obj.text, meta),
+      source: { kind: 'v0', claim: shortClaim },
+      claim: shortClaim,
       currentStatus: 'active',
       isLegacy: true,
     };
   }
 
+  const shortClaim = buildCanonicalObjectFromLegacy(decrypted, {});
   return {
-    claim: buildCanonicalObjectFromLegacy(decrypted, {}),
+    source: { kind: 'v0', claim: shortClaim },
+    claim: shortClaim,
     currentStatus: 'active',
     isLegacy: true,
   };
@@ -205,6 +301,113 @@ function buildCanonicalObjectFromLegacy(
   };
 }
 
+// ─── v1 projection ────────────────────────────────────────────────────────────
+
+/** v1 shape used to drive buildV1ClaimBlob from a (v0 or v1) source. */
+interface V1Projection {
+  text: string;
+  type: MemoryType;
+  source: MemorySource;
+  scope?: MemoryScope;
+  volatility?: MemoryVolatility;
+  reasoning?: string;
+  entities?: Array<{ name: string; type: string; role?: string }>;
+  importance: number;
+  confidence: number;
+}
+
+/**
+ * Project a source blob (v1 or v0 short-key) into the v1 shape needed by
+ * `buildV1ClaimBlob`. For v1 sources this is identity; for v0 sources we
+ * upgrade the category / source fields per the spec's legacy-mapping table
+ * (`fact|context|decision → claim`, `rule → directive`, `goal → commitment`,
+ * etc.). Anything we can't determine falls back to a sensible default so the
+ * build call doesn't throw.
+ */
+function projectToV1(src: V1PinBlob | V0PinBlob, defaultSourceAgent: string): V1Projection {
+  if (src.kind === 'v1') {
+    return {
+      text: src.text,
+      type: src.type,
+      source: src.source,
+      scope: src.scope,
+      volatility: src.volatility,
+      reasoning: src.reasoning,
+      entities: src.entities,
+      importance: src.importance,
+      confidence: src.confidence,
+    };
+  }
+
+  // v0 path — upgrade short-key claim to v1.
+  const claim = src.claim;
+  const text = typeof claim.t === 'string' ? claim.t : '';
+  const v0Category = typeof claim.c === 'string' ? claim.c : 'fact';
+  // Legacy short category keys back to type names (reverse of TYPE_TO_CATEGORY_V0).
+  const V0_CATEGORY_TO_V0_TYPE: Record<string, string> = {
+    fact: 'fact',
+    pref: 'preference',
+    dec: 'decision',
+    epi: 'episodic',
+    goal: 'goal',
+    ctx: 'context',
+    sum: 'summary',
+    rule: 'rule',
+    ent: 'fact', // entity records don't round-trip as v1 claims; fall back
+    dig: 'summary',
+    claim: 'claim',
+  };
+  const v0TypeToken = V0_CATEGORY_TO_V0_TYPE[v0Category] ?? 'fact';
+  // Use the shared v0→v1 map for the upgrade.
+  const v1Type: MemoryType = (V0_TO_V1_TYPE as Record<string, MemoryType>)[v0TypeToken] ?? 'claim';
+
+  const importance = typeof claim.i === 'number'
+    ? Math.max(1, Math.min(10, Math.round(claim.i as number)))
+    : 5;
+  const confidence = typeof claim.cf === 'number' ? (claim.cf as number) : 0.85;
+
+  // v0 `sa` isn't a provenance source — it's a "source agent" string like
+  // "openclaw-plugin". Map heuristically: if it looks like an agent-style
+  // string (contains "plugin"/"agent"/"derived"), mark it as appropriate;
+  // otherwise default to "user-inferred" so Tier 1 reranker doesn't give it
+  // "user" trust (which would be wrong for legacy blobs with no provenance
+  // signal).
+  const sa = typeof claim.sa === 'string' ? claim.sa : defaultSourceAgent;
+  let v1Source: MemorySource = 'user-inferred';
+  const saLower = sa.toLowerCase();
+  if (saLower.includes('derived') || saLower.includes('digest') || saLower.includes('consolidat')) {
+    v1Source = 'derived';
+  } else if (saLower.includes('assistant')) {
+    v1Source = 'assistant';
+  } else if (saLower.includes('extern') || saLower.includes('mem0') || saLower.includes('import')) {
+    v1Source = 'external';
+  }
+
+  const entities = Array.isArray(claim.e)
+    ? (claim.e as unknown[])
+        .map((e) => {
+          if (!e || typeof e !== 'object') return null;
+          const entity = e as Record<string, unknown>;
+          const name = typeof entity.n === 'string' ? entity.n : '';
+          const entType = typeof entity.tp === 'string' ? entity.tp : 'concept';
+          if (!name) return null;
+          const out: { name: string; type: string; role?: string } = { name, type: entType };
+          if (typeof entity.r === 'string' && entity.r.length > 0) out.role = entity.r;
+          return out;
+        })
+        .filter((x): x is { name: string; type: string; role?: string } => x !== null)
+    : undefined;
+
+  return {
+    text,
+    type: v1Type,
+    source: v1Source,
+    importance,
+    confidence,
+    entities,
+  };
+}
+
 // ─── Pure core: executePinOperation ───────────────────────────────────────────
 
 /** Injected dependencies for the pin operation (transport + crypto + indexing). */
@@ -338,30 +541,41 @@ export async function executePinOperation(
     };
   }
 
-  // 4. Build the new canonical claim with updated status + supersedes link
-  const newClaimObj = { ...parsed.claim };
-  if (targetStatus === 'active') {
-    // Active is the canonical default — omit `st` entirely.
-    delete newClaimObj.st;
-  } else {
-    newClaimObj.st = HUMAN_TO_SHORT[targetStatus];
-  }
-  newClaimObj.sup = factId;
-  // Refresh extraction timestamp so downstream consumers can tell this is a new event.
-  newClaimObj.ea = new Date().toISOString();
-  // Carry source agent forward if present, else stamp it.
-  if (typeof newClaimObj.sa !== 'string' || newClaimObj.sa.length === 0) {
-    newClaimObj.sa = deps.sourceAgent;
-  }
+  // 4. Build the new canonical v1.1 claim with pin_status + superseded_by link.
+  //
+  // The new blob is ALWAYS v1.1 shaped (schema_version "1.0", pin_status
+  // present) regardless of the source blob's format. v0 sources are upgraded
+  // to v1 on the pin path; v1 sources round-trip their metadata (source,
+  // scope, reasoning, entities, volatility) into the new blob.
+  const pinStatus: PinStatus = targetStatus === 'pinned' ? 'pinned' : 'unpinned';
+  const newFactId = crypto.randomUUID();
+
+  // Project the source blob into v1 shape. For v0 sources we upgrade on the
+  // fly: short-key `c` → v1 type, `sa` → source (heuristic), etc.
+  const v1View = projectToV1(parsed.source, deps.sourceAgent);
 
   let canonicalJson: string;
   try {
-    canonicalJson = getWasm().canonicalizeClaim(JSON.stringify(newClaimObj));
+    canonicalJson = buildV1ClaimBlob({
+      id: newFactId,
+      text: v1View.text,
+      type: v1View.type,
+      source: v1View.source,
+      scope: v1View.scope,
+      volatility: v1View.volatility,
+      reasoning: v1View.reasoning,
+      entities: v1View.entities,
+      importance: v1View.importance,
+      confidence: v1View.confidence,
+      createdAt: new Date().toISOString(),
+      supersededBy: factId,
+      pinStatus,
+    });
   } catch (err) {
     return {
       success: false,
       fact_id: factId,
-      error: `Failed to canonicalize updated claim: ${err instanceof Error ? err.message : String(err)}`,
+      error: `Failed to build v1 claim blob: ${err instanceof Error ? err.message : String(err)}`,
     };
   }
 
@@ -378,22 +592,22 @@ export async function executePinOperation(
   }
 
   // 5b. Regenerate trapdoors so the new fact is findable by the same text.
-  const newClaimText = typeof parsed.claim.t === 'string' ? parsed.claim.t : '';
-  const entityNames: string[] = Array.isArray(parsed.claim.e)
-    ? (parsed.claim.e as unknown[])
-        .map((e) => (e && typeof (e as { n?: unknown }).n === 'string' ? (e as { n: string }).n : ''))
-        .filter((n): n is string => n.length > 0)
+  const entityNames: string[] = v1View.entities
+    ? v1View.entities.map((e) => e.name).filter((n): n is string => typeof n === 'string' && n.length > 0)
     : [];
   let regenerated: { blindIndices: string[]; encryptedEmbedding?: string };
   try {
-    regenerated = await deps.generateIndices(newClaimText, entityNames);
+    regenerated = await deps.generateIndices(v1View.text, entityNames);
   } catch {
     regenerated = { blindIndices: [] };
   }
 
   // 6. Build tombstone + new protobuf payloads.
-  // Plugin tombstone convention matches the rest of the plugin: `encryptedBlob: '00'`,
-  // empty indices, decayScore=0, source='tombstone'.
+  //
+  // Tombstone: empty blob ('00'), empty indices, decayScore=0, source='tombstone'.
+  // Written at the DEFAULT protobuf version (legacy v3) because tombstone rows
+  // carry no inner blob — the version field is irrelevant for readers and
+  // writing v3 keeps round-trip compat with any pre-v1 tombstone parser.
   const tombstonePayload: FactPayload = {
     id: factId,
     timestamp: new Date().toISOString(),
@@ -406,7 +620,6 @@ export async function executePinOperation(
     agentId: deps.sourceAgent,
   };
 
-  const newFactId = crypto.randomUUID();
   const newPayload: FactPayload = {
     id: newFactId,
     timestamp: new Date().toISOString(),
@@ -420,7 +633,13 @@ export async function executePinOperation(
     encryptedEmbedding: regenerated.encryptedEmbedding,
   };
 
-  const payloads = [encodeFactProtobufLocal(tombstonePayload), encodeFactProtobufLocal(newPayload)];
+  // Outer protobuf version: v=4 for the new v1 claim, default (legacy v3)
+  // for the tombstone. This is the core of the bug-2 fix — previously both
+  // payloads went out at version=3 and the inner blob was v0 short-key.
+  const payloads = [
+    encodeFactProtobufLocal(tombstonePayload, /* version = legacy v3 */ 3),
+    encodeFactProtobufLocal(newPayload, PROTOBUF_VERSION_V4),
+  ];
 
   // 6b. Slice 2f: consult decisions.jsonl to see if this pin/unpin contradicts
   // a prior auto-resolution. If so, append a counterexample to feedback.jsonl