claude-smart 0.2.42 → 0.2.44

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "reflexio",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  }
+}

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/HEARTBEAT.md

@@ -0,0 +1,6 @@
+## Reflexio Consolidation Check
+
+tasks:
+  - description: "Check if reflexio consolidation is due"
+    tool: reflexio_consolidation_check
+    interval: 24h

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/README.md

@@ -0,0 +1,84 @@
+# Reflexio Embedded
+
+Openclaw plugin for user profile and playbook extraction — learns your preferences, corrections, and workflows across sessions using Openclaw's native memory engine, hooks, and sub-agents. No Reflexio server required.
+
+## Prerequisites
+
+- [Openclaw CLI](https://docs.openclaw.ai) (>= 2026.3.24)
+- Node.js
+
+## Install
+
+```bash
+# 1. Install and enable the plugin
+openclaw plugins install /path/to/this/directory
+openclaw plugins enable reflexio-embedded
+
+# 2. Enable the active-memory plugin (required for memory search)
+openclaw plugins enable active-memory
+openclaw config set plugins.entries.active-memory.config.agents '["*"]'
+
+# 3. Register .reflexio/ as a memory search path
+openclaw config set agents.defaults.memorySearch.extraPaths '[".reflexio/"]' --strict-json
+
+# 4. Restart the gateway to pick up changes
+openclaw gateway restart
+```
+
+Verify it loaded:
+
+```bash
+openclaw plugins inspect reflexio-embedded
+```
+
+## Uninstall
+
+```bash
+# 1. Remove the plugin
+openclaw plugins disable reflexio-embedded
+openclaw plugins uninstall --force reflexio-embedded
+
+# 2. Clean up state files
+rm -f ~/.openclaw/reflexio-consolidation-state.json
+
+# 3. Restart the gateway
+openclaw gateway restart
+```
+
+Your `.reflexio/` user data (profiles and playbooks) is preserved by default. To remove it:
+
+```bash
+rm -rf .reflexio/
+```
+
+## What it does
+
+- **Profile extraction** — automatically captures user preferences, facts, and corrections from conversations into `.reflexio/profiles/`
+- **Playbook capture** — records recurring workflows and patterns into `.reflexio/playbooks/`
+- **Dedup and contradiction resolution** — new entries are compared against existing ones via LLM; overlapping content is merged, contradictions resolved (new wins), and non-contradicted facts preserved
+- **Consolidation** — periodic heartbeat-triggered sweep that clusters similar entries and merges duplicates
+- **TTL management** — profiles can have time-to-live values; expired entries are swept automatically
+
+## Configuration
+
+Override defaults in your `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "reflexio-embedded": {
+        "config": {
+          "dedup": { "shallow_threshold": 0.4, "top_k": 5 },
+          "consolidation": { "threshold_hours": 24 }
+        }
+      }
+    }
+  }
+}
+```
+
+## Learn more
+
+Full project source, design docs, and development setup:
+https://github.com/ReflexioAI/reflexio/tree/main/reflexio/integrations/openclaw-embedded

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: reflexio-embedded
+description: "Captures user facts and procedural corrections into .reflexio/ so the agent learns across sessions. Use when: (1) user states a preference, fact, config, or constraint; (2) user corrects the agent and confirms the fix with an explicit 'good'/'perfect' or by moving on without re-correcting for 1-2 turns; (3) at start of a user turn, to retrieve relevant facts and playbooks from past sessions."
+metadata:
+---
+
+# Reflexio Embedded Skill
+
+Captures user facts (profiles) and procedural corrections (playbooks) into `.reflexio/`, so the agent learns across sessions. All memory lives in Openclaw's native primitives — no external service required.
+
+## First-time setup per agent
+
+If `.reflexio/.setup_complete_<agentId>` does NOT exist (where `<agentId>` is your current agent id), perform this one-time check. The setup step runs probing commands via `exec` and asks for approval before making changes.
+
+**Steps:**
+
+1. Probe current config:
+   - `openclaw config get plugins.entries.active-memory.config.agents`
+   - `openclaw config get agents.defaults.memorySearch.extraPaths`
+   - `openclaw memory status --deep`
+
+2. If active-memory is not targeting this agent:
+   Ask user: *"To auto-inject relevant facts into each turn, I can enable active-memory for this agent. OK if I run `openclaw config set plugins.entries.active-memory.config.agents '[\"<agentId>\"]' --strict-json`?"*
+   On approval, run the command.
+
+3. If `.reflexio/` is not registered as an extraPath:
+   Ask user: *"I need to register .reflexio/ as a memory path. OK if I run `openclaw config set agents.defaults.memorySearch.extraPaths '[\".reflexio/\"]' --strict-json`?"*
+   On approval, run the command.
+
+4. If no embedding provider is configured (FTS-only mode):
+   Tell user: *"Vector search requires an embedding API key (OpenAI, Gemini, Voyage, or Mistral). The plugin works without one but retrieval quality drops. Would you like guidance on adding one?"*
+   If yes, guide them through `openclaw config set` or `openclaw configure`.
+
+5. On each decline, note the degraded mode but do not block:
+   - No active-memory → you must run `openclaw memory search` via exec at turn start (see "Retrieval" section below).
+   - No extraPath → WARN the user the plugin cannot function without this step.
+   - No embedding → continue with FTS-only.
+
+6. When all checks resolved (approved or accepted with warning): create the marker:
+   ```bash
+   mkdir -p .reflexio
+   touch .reflexio/.setup_complete_<agentId>
+   ```
+
+**If exec is not available** (strict admin policy): fall back to telling the user the exact commands to run manually.
+
+## First-Use Initialisation
+
+Before any write, ensure `.reflexio/` and its subdirectories exist. This is idempotent — safe to run every session:
+
+```bash
+mkdir -p .reflexio/profiles .reflexio/playbooks
+```
+
+Never overwrite existing files. Never write secrets, tokens, private keys, environment variables, or credentials into `.reflexio/` files. When capturing a fact involves a user-pasted snippet that contains credentials, redact first.
+
+## Quick Reference
+
+| Situation                                                 | Action                                     |
+|-----------------------------------------------------------|--------------------------------------------|
+| User states preference, fact, config, or constraint       | `reflexio_write_profile` tool              |
+| User correction → you adjust → user confirms              | `reflexio_write_playbook` tool             |
+| Start of user turn, need context                          | `reflexio_search` tool                     |
+| Unsure whether to capture                                 | Skip; batch pass at session-end has a second shot |
+
+## Detection Triggers
+
+### Profile signals (write immediately, same turn)
+
+- **Preferences**: "I prefer X", "I like Y", "I don't like Z", "I always do Q"
+- **Facts about self**: "I'm a [role]", "my timezone is X", "I've been doing Y for Z years"
+- **Config**: "use X", "our team uses Y", "the repo is at Z"
+- **Constraints**: "I'm vegetarian", "no dairy", "I can't X", "don't use Y"
+
+For each such signal, call the `reflexio_write_profile` tool with a kebab-case topic slug and an appropriate TTL. See "TTL Selection" below.
+
+### Playbook signals (write AFTER confirmation)
+
+Playbooks require a specific multi-turn pattern:
+
+1. **Correction**: *"No, that's wrong"*, *"Actually..."*, *"Don't do X"*, *"Not like that"*, *"We don't use X here"*.
+2. **You adjust**: you redo the work per the correction.
+3. **Confirmation** (required — without this, do NOT write a playbook):
+   - Explicit: *"good"*, *"perfect"*, *"yes that's right"*, *"correct"*.
+   - Implicit: the user moves to an unrelated topic without re-correcting for 1-2 more turns.
+
+**Explicit don't-write rule**: if you see a correction without subsequent confirmation, do not write a playbook. The fix may be wrong; let the batch pass at session end re-evaluate.
+
+## Retrieval
+
+### When Active Memory is enabled
+
+Your turn context may already contain Reflexio-prefixed entries injected by Active Memory. Incorporate them before responding. No tool call needed.
+
+### Fallback when Active Memory is absent
+
+At the start of each user turn, call the `reflexio_search` tool with:
+- query: "<user's message>"
+
+The tool handles query preprocessing and memory search internally.
+Incorporate any results into your response. Skip if the user's message is trivial.
+
+**Important:** Do NOT use the `memory_search` tool (returns config, not results)
+or `exec` with `openclaw memory search` — use the `reflexio_search` tool instead.
+
+## File Format
+
+**Do NOT construct filenames or frontmatter by hand.** Use the registered tools (`reflexio_write_profile`, `reflexio_write_playbook`). They generate IDs, enforce the frontmatter schema, and write atomically.
+
+### Profile template (for mental model — the script emits this)
+
+```markdown
+---
+type: profile
+id: prof_<nanoid>
+created: <ISO timestamp>
+ttl: <enum>
+expires: <ISO date or "never">
+supersedes: [<old_id>]   # optional, only after a merge
+---
+
+<1-3 sentences, one fact per file>
+```
+
+### Playbook template
+
+```markdown
+---
+type: playbook
+id: pbk_<nanoid>
+created: <ISO timestamp>
+supersedes: [<old_id>]   # optional
+---
+
+## When
+<1-sentence trigger — this is the search anchor; make it a noun phrase>
+
+## What
+<2-3 sentences of the procedural rule; DO / DON'T as actually observed>
+
+## Why
+<rationale, can be longer — reference only, not recall content>
+```
+
+### How to invoke
+
+**Profile:** Call the `reflexio_write_profile` tool with:
+- slug: "diet-vegan"
+- ttl: "infinity"
+- body: "User is vegan. No meat, no fish, no dairy, no eggs."
+
+**Playbook:** Call the `reflexio_write_playbook` tool with:
+- slug: "commit-no-ai-attribution"
+- body: "## When\nComposing a git commit message.\n\n## What\nNo AI-attribution trailers.\n\n## Why\nUser corrected this."
+
+**Retrieve context:** Call the `reflexio_search` tool with:
+- query: "user's question here"
+
+All tools handle preprocessing, memory search, contradiction detection, and file operations internally. You only detect the signal, compose the content, and call the tool.
+
+## TTL Selection (profiles only)
+
+- `infinity` — durable, non-perishable facts (diet, name, permanent preferences)
+- `one_year` — stable but could plausibly change (address, role, team)
+- `one_quarter` — current focus (active project, sprint theme)
+- `one_month` — short-term context
+- `one_week` / `one_day` — transient (today's agenda, this week's priorities)
+
+Pick the most generous TTL that still reflects reality. When in doubt, prefer `infinity` — let dedup handle later contradictions via supersession.
+
+## Safety
+
+- **Never write secrets.** No API keys, tokens, access tokens, private keys, environment variables, OAuth secrets, auth headers. If the user's message contains any of these, redact them before writing.
+- **Redact pasted code.** User-pasted snippets often contain credentials. Strip them first.
+- **PII.** Do not capture PII beyond what's operationally useful (name, timezone, role are fine; government IDs, addresses, phone numbers only if explicitly relevant).
+
+## Best Practices
+
+1. **Write immediately** on a clear signal. Don't queue to session-end — that's Flow C's job; you have a different role.
+2. **One fact per profile file.** Multi-fact files are harder to dedupe and easier to contradict.
+3. **Trigger phrase = search anchor.** Write `## When` as a noun phrase describing the situation, not a sentence. Retrieval hits on semantic similarity to this field.
+4. **Skip writing when uncertain.** Flow C has a second pass over the full transcript. It's better to let it handle ambiguous cases.
+5. **Prefer shorter TTL for transient facts.** Don't let "working on project X" accumulate as infinity-TTL cruft.
+
+## Opt-in Hook
+
+This skill works standalone — your in-session Flow A (profile) and Flow B (playbook) writes populate `.reflexio/` without any hook.
+
+The optional hook (`hook/` directory of this plugin) adds two capabilities:
+
+1. **TTL sweep at session start**: deletes expired profiles before Active Memory runs.
+2. **Session-end batch extraction (Flow C)**: on `session:compact:before`, `command:stop`, or `command:reset`, spawns a `reflexio-extractor` sub-agent that extracts profiles/playbooks from the full transcript and runs shallow pairwise dedup.
+
+See this plugin's `README.md` for install instructions (runs via `./scripts/install.sh`). If the hook is not installed, Flows A+B still work.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/_meta.json

@@ -0,0 +1,6 @@
+{
+  "ownerId": "reflexio-ai",
+  "slug": "openclaw-embedded",
+  "version": "0.1.0",
+  "publishedAt": 1777000000000
+}

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/agents/reflexio-extractor.md

@@ -0,0 +1,45 @@
+---
+name: reflexio-extractor
+description: "Scoped sub-agent for openclaw-embedded Flow C. Extracts profiles and playbooks from a transcript, then runs shallow pairwise dedup against existing .reflexio/ entries."
+tools:
+  - memory_search
+  - file_read
+  - file_write
+  - file_delete
+  - reflexio_write_profile
+  - reflexio_write_playbook
+  - reflexio_search
+runTimeoutSeconds: 120
+---
+
+You are a one-shot sub-agent that extracts profiles and playbooks from a conversation transcript, then deduplicates against existing entries in `.reflexio/`.
+
+## Your workflow
+
+1. **Profile extraction**: load `prompts/profile_extraction.md`, substitute `{transcript}` with the provided transcript and `{existing_profiles_context}` with results from `memory_search(top_k=10, filter={type: profile})`. Call `llm-task` with the substituted prompt and output schema. You receive a list of profile candidates.
+
+2. **Playbook extraction**: same process with `prompts/playbook_extraction.md`. You receive a list of playbook candidates.
+
+3. **For each candidate**:
+   For profiles:
+   ```
+   Call the `reflexio_write_profile` tool with: slug="<slug>", ttl="<ttl>", body="<content>"
+   ```
+   For playbooks:
+   ```
+   Call the `reflexio_write_playbook` tool with: slug="<slug>", body="<content>"
+   ```
+   The tools handle dedup + supersession internally — no separate file deletion needed.
+
+4. Exit. Openclaw's file watcher picks up the changes and reindexes.
+
+## Constraints
+
+- Never write secrets, tokens, API keys, or environment variables into `.md` files.
+- On any LLM call failure: skip that candidate, log to stderr, continue.
+- On tool call failure: skip; state unchanged; next cycle retries.
+- You have 120 seconds. If approaching the limit, exit cleanly; any completed writes are durable.
+
+## Tool scope
+
+You have access only to: `memory_search`, `file_read`, `file_write`, `file_delete`, `reflexio_write_profile`, `reflexio_write_playbook`, `reflexio_search`. You do NOT have `sessions_spawn`, `web`, or network tools.

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/hook/handler.ts

@@ -0,0 +1,214 @@
+// Reflexio Embedded — pure handler logic.
+//
+// This module is intentionally decoupled from the Openclaw SDK so that:
+//   1. The TTL sweep / transcript serialization logic is easy to unit-test via
+//      `smoke-test.js` without spinning up a gateway.
+//   2. Swapping the SDK wiring (see ../index.ts) never requires touching the
+//      behavioural code here.
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** Minimal subset of the Openclaw runtime we actually use. */
+type SubagentRuntime = {
+  subagent?: {
+    run: (params: {
+      sessionKey: string;
+      message: string;
+      extraSystemPrompt?: string;
+      lane?: string;
+      idempotencyKey?: string;
+    }) => Promise<{ runId: string }>;
+  };
+};
+
+type Logger = {
+  info?: (msg: string) => void;
+  warn?: (msg: string) => void;
+  error?: (msg: string) => void;
+};
+
+/**
+ * Find the workspace root. Openclaw passes it via ctx.workspaceDir; fall back
+ * to the WORKSPACE env var (handy for smoke tests) and finally process.cwd().
+ */
+export function resolveWorkspace(hint?: string): string {
+  if (hint && hint.trim()) return hint;
+  if (process.env.WORKSPACE) return process.env.WORKSPACE;
+  return process.cwd();
+}
+
+/**
+ * TTL sweep: scan .reflexio/profiles/*.md and unlink expired files.
+ * Cheap: filesystem + YAML frontmatter parse only. Target <50ms for dozens of files.
+ */
+export async function ttlSweepProfiles(workspaceHint?: string): Promise<void> {
+  const workspace = resolveWorkspace(workspaceHint);
+  const dir = path.join(workspace, ".reflexio", "profiles");
+  if (!fs.existsSync(dir)) return;
+
+  const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
+  const entries = await fs.promises.readdir(dir);
+
+  for (const entry of entries) {
+    if (!entry.endsWith(".md")) continue;
+    const full = path.join(dir, entry);
+    let contents: string;
+    try {
+      contents = await fs.promises.readFile(full, "utf8");
+    } catch {
+      continue;
+    }
+    const expiresMatch = /^expires:\s*(\S+)/m.exec(contents);
+    if (!expiresMatch) continue;
+    const expires = expiresMatch[1];
+    if (expires === "never") continue;
+    if (expires < today) {
+      try {
+        await fs.promises.unlink(full);
+      } catch (err) {
+        console.error(
+          `[reflexio-embedded] ttl sweep: failed to unlink ${full}: ${err}`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Short system-prompt reminder injected on every agent run so the LLM knows
+ * the Reflexio SKILL.md is available.
+ */
+export function injectBootstrapReminder(): string {
+  return [
+    "# Reflexio Embedded",
+    "",
+    "This agent has the openclaw-embedded plugin installed. Its SKILL.md",
+    "describes how to capture user facts and corrections into .reflexio/.",
+    "",
+    "Load the skill when: user states a preference/fact/config, user corrects",
+    "you and later confirms the fix, or you need to retrieve past context.",
+  ].join("\n");
+}
+
+type TranscriptMessage = {
+  role?: string;
+  content?: unknown;
+  timestamp?: string;
+};
+
+/** Decide whether the current transcript is worth extracting from. */
+function transcriptWorthExtracting(messages: unknown[] | undefined): boolean {
+  if (!Array.isArray(messages) || messages.length < 2) return false;
+  return messages.some((m) => (m as TranscriptMessage).role === "user");
+}
+
+/** Serialize transcript into a plain-text form suitable for the sub-agent task prompt. */
+function serializeTranscript(messages: unknown[] | undefined): string {
+  if (!Array.isArray(messages)) return "";
+  return messages
+    .map((raw) => {
+      const m = raw as TranscriptMessage;
+      const role = m.role ?? "unknown";
+      const content =
+        typeof m.content === "string" ? m.content : JSON.stringify(m.content);
+      const ts = m.timestamp ? ` [${m.timestamp}]` : "";
+      return `### ${role}${ts}\n${content}`;
+    })
+    .join("\n\n");
+}
+
+/**
+ * Build the task prompt handed to the reflexio-extractor sub-agent. The
+ * sub-agent's system prompt already contains its workflow (from
+ * agents/reflexio-extractor.md). This prompt just provides the transcript and
+ * reminds it of its job.
+ */
+function buildExtractionTaskPrompt(
+  messages: unknown[] | undefined,
+  sessionFile: string | undefined,
+): string {
+  const parts = [
+    "Run your extraction workflow on the recent transcript.",
+    "",
+    "Follow your system prompt: extract profiles and playbooks, then run shallow pairwise dedup against existing .reflexio/ entries.",
+    "",
+  ];
+  const transcript = serializeTranscript(messages);
+  if (transcript) {
+    parts.push("## Transcript", "", transcript);
+  } else if (sessionFile) {
+    parts.push(
+      "## Transcript",
+      "",
+      `The transcript lives on disk at: ${sessionFile}`,
+      "Read that file to reconstruct the session.",
+    );
+  } else {
+    parts.push(
+      "## Transcript",
+      "",
+      "No in-memory transcript is available for this event; skip if you cannot find a session file.",
+    );
+  }
+  return parts.join("\n");
+}
+
+export type SpawnExtractorParams = {
+  runtime: SubagentRuntime | undefined;
+  workspaceDir?: string;
+  sessionKey?: string;
+  messages?: unknown[];
+  sessionFile?: string;
+  extraSystemPrompt?: string;
+  log?: Logger;
+  reason: string;
+};
+
+/**
+ * Fire-and-forget spawn of the reflexio-extractor sub-agent. The caller should
+ * NOT await the run itself — Openclaw manages the lifecycle via its Background
+ * Tasks ledger.
+ *
+ * Returns the runId when the spawn succeeds (caller can await the spawn to be
+ * sure the request reached the runtime, but not the sub-agent's completion).
+ */
+export async function spawnExtractor(
+  params: SpawnExtractorParams,
+): Promise<string | undefined> {
+  const { runtime, sessionKey, messages, sessionFile, extraSystemPrompt, log, reason } = params;
+
+  if (!transcriptWorthExtracting(messages) && !sessionFile) {
+    return undefined;
+  }
+  const runFn = runtime?.subagent?.run;
+  if (!runFn) {
+    log?.warn?.(
+      "[reflexio-embedded] runtime.subagent.run unavailable; skipping extraction",
+    );
+    return undefined;
+  }
+
+  // Session-key namespacing: each extractor run gets its own sub-session so
+  // the parent session transcript is not polluted.
+  const childSessionKey = `reflexio-extractor:${sessionKey ?? "unknown"}:${Date.now()}`;
+  const message = buildExtractionTaskPrompt(messages, sessionFile);
+
+  try {
+    const result = await runFn({
+      sessionKey: childSessionKey,
+      message,
+      extraSystemPrompt,
+      lane: "reflexio-extractor",
+      idempotencyKey: `reflexio-extractor:${sessionKey ?? "unknown"}:${reason}`,
+    });
+    log?.info?.(
+      `[reflexio-embedded] extractor spawned (runId=${result.runId}, reason=${reason})`,
+    );
+    return result.runId;
+  } catch (err) {
+    log?.error?.(
+      `[reflexio-embedded] failed to spawn extractor (reason=${reason}): ${err}`,
+    );
+    return undefined;
+  }
+}

package/plugin/vendor/reflexio/reflexio/integrations/openclaw-embedded/plugin/hook/setup.ts

@@ -0,0 +1,55 @@
+// Workspace auto-setup.
+//
+// On first load after install, appends the heartbeat consolidation check
+// to the workspace HEARTBEAT.md. Skills are served from the extension dir
+// via the manifest's "skills" field. Agents are injected via extraSystemPrompt.
+// No workspace file copying needed — everything lives in the extension dir.
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+function resolveOpenclawHome(): string {
+  return process.env.OPENCLAW_HOME || path.join(os.homedir(), ".openclaw");
+}
+
+/**
+ * Strip all existing reflexio heartbeat blocks from content.
+ * Splits by double-newline into paragraphs and drops any containing the tool name.
+ */
+function stripReflexioHeartbeatBlocks(content: string): string {
+  const paragraphs = content.split(/\n\n+/);
+  const cleaned = paragraphs.filter(
+    (p) => !p.includes("reflexio_consolidation_check") && !p.includes("Reflexio Consolidation Check")
+  );
+  return cleaned.join("\n\n").trim();
+}
+
+/**
+ * Append HEARTBEAT.md content to the workspace. Idempotent — strips all
+ * existing reflexio blocks first, then appends one canonical block.
+ *
+ * @param pluginDir - The plugin's install directory (import.meta.dirname)
+ */
+export function setupWorkspaceResources(pluginDir: string): void {
+  const workspace = path.join(resolveOpenclawHome(), "workspace");
+
+  const heartbeatSrc = path.join(pluginDir, "HEARTBEAT.md");
+  const heartbeatDest = path.join(workspace, "HEARTBEAT.md");
+  if (!fs.existsSync(heartbeatSrc)) return;
+
+  const heartbeatContent = fs.readFileSync(heartbeatSrc, "utf8");
+
+  let existing = "";
+  try {
+    existing = fs.readFileSync(heartbeatDest, "utf8");
+  } catch {
+    // file doesn't exist yet
+  }
+
+  // Always strip existing reflexio blocks (handles duplicates from prior installs),
+  // then append one canonical block
+  const cleaned = stripReflexioHeartbeatBlocks(existing);
+  const final = cleaned + (cleaned ? "\n\n" : "") + heartbeatContent;
+  fs.mkdirSync(workspace, { recursive: true });
+  fs.writeFileSync(heartbeatDest, final, "utf8");
+}