@massa-ai/cursor-plugin 1.52.0 → 1.54.1

package/.cursor-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "massa-ai",
-  "version": "1.52.0",
+  "version": "1.54.1",
   "description": "massa-ai — semantic code search, memory, and context compression for Cursor"
 }

package/install.sh

@@ -11,15 +11,38 @@
 # MCP registration is delegated to scripts/install-agents.sh, the single writer
 # of host MCP config. This installer no longer ships a plugin-local mcp.json.
 #
-# Cursor 3.14 also bridges the Claude marketplace registry from ~/.claude and
-# loads any plugin listed there IN ADDITION to a local install — a machine
-# with both would load massa-ai twice and fire every hook twice (AD-017). At
-# USER scope, this installer prefers the bridge: when ~/.claude lists massa-ai
-# as installed and enabled, it skips its own local plugin copy and hook
-# wiring (removing a pre-existing local copy so one run converges), while
-# still writing the flat subagents, harness skills, and MCP registration this
-# installer always owns. Project-scope installs are unaffected — ~/.claude is
-# a user surface, never a project one.
+# LOCAL IS THE DEFAULT ROUTE. The Claude bridge is opt-in (--prefer-bridge).
+#
+# Cursor can bridge the Claude marketplace registry from ~/.claude — observed
+# live in Cursor 3.14's "Cursor Plugins" exthost log on 2026-08-05
+# ("loadClaudePlugin massa-ai@massa-ai"). This installer used to PREFER that
+# bridge at user scope: on detection it deleted its own plugin directory and
+# stripped its hook wiring, on the premise that the bridge loads the whole
+# plugin.
+#
+# Measured on Cursor 3.16.17 (2026-08-17), with massa-ai listed and
+# `enabledPlugins` true in ~/.claude, that premise is at best half true:
+#
+#   hooks    → fire in Cursor
+#   plugin   → absent from the Cursor UI
+#   commands → absent (all 46 workflow commands)
+#
+# So bridge-preference silently withheld a working local install, and the user
+# lost every workflow command with nothing replacing them. Detection reads
+# ~/.claude, which is a fact about CLAUDE's files — never proof that Cursor
+# loaded anything from them — and nothing here can observe the difference.
+#
+# The default therefore installs everything locally. --prefer-bridge (or
+# MASSA_AI_CURSOR_PREFER_BRIDGE=1) restores the old behaviour for anyone whose
+# bridge does deliver hooks.
+#
+# AD-017 TRADE-OFF, STATED PLAINLY: if the bridge IS delivering hooks and you
+# take the default, both sources are live and every hook fires TWICE. The
+# install warns when it detects that combination. Choose --prefer-bridge, or
+# disable massa-ai in ~/.claude/settings.json, to keep exactly one source.
+#
+# Project-scope installs never consult the bridge — ~/.claude is a user
+# surface, never a project one.
 #
 # Idempotent: re-running is a no-op when owned entries already present.
 # Uninstall removes only ownership-marked entries + the plugin directory,
@@ -29,6 +52,13 @@
 #   apps/cursor-plugin/install.sh             # install at user scope (~/.cursor)
 #   apps/cursor-plugin/install.sh --user      #   (same)
 #   apps/cursor-plugin/install.sh --project  # install at project scope (./.cursor)
+#   apps/cursor-plugin/install.sh --prefer-bridge # leave hook wiring to the
+#                                             # Claude bridge instead of
+#                                             # installing it locally; use when
+#                                             # bridge-delivered hooks DO fire
+#                                             # in your Cursor, to avoid every
+#                                             # hook firing twice. Same as
+#                                             # MASSA_AI_CURSOR_PREFER_BRIDGE=1
 #   apps/cursor-plugin/install.sh --uninstall # remove owned entries + plugin dir
 #   apps/cursor-plugin/install.sh -h|--help   # show this help
 
@@ -41,11 +71,26 @@ CLAUDE_PLUGIN_BIN="$REPO_ROOT/apps/claude-plugin/hooks/massa-ai-hook.ts"
 SCOPE="user"
 UNINSTALL=0
 DRY_RUN=0
+# Local is the DEFAULT route; the Claude bridge is opt-in.
+#
+# Bridge detection reads ~/.claude — a fact about CLAUDE's files — and infers
+# from it that Cursor is loading massa-ai. That inference cannot be verified
+# from here, and it was measured wrong on Cursor 3.16.17: the plugin and its
+# 46 workflow commands were absent from the Cursor UI while ~/.claude said the
+# plugin was installed and enabled. Preferring the bridge by default therefore
+# meant silently withholding a working local install on the strength of a
+# claim about a different product.
+#
+# So the default installs everything locally, and --prefer-bridge (or
+# MASSA_AI_CURSOR_PREFER_BRIDGE=1) opts into leaving hook wiring to the
+# bridge. See the AD-017 double-fire note where PREFER_BRIDGE is consumed.
+PREFER_BRIDGE="${MASSA_AI_CURSOR_PREFER_BRIDGE:-0}"
 
 for arg in "$@"; do
   case "$arg" in
     --user) SCOPE="user" ;;
     --project) SCOPE="project" ;;
+    --prefer-bridge) PREFER_BRIDGE=1 ;;
     --uninstall) UNINSTALL=1 ;;
     --quiet) MASSA_AI_VERBOSE=0 ;;
     --verbose) MASSA_AI_VERBOSE=1 ;;
@@ -249,14 +294,37 @@ if (typeof cfg.hooks !== "object" || cfg.hooks === null) cfg.hooks = {};
 
 const hooks = cfg.hooks;
 
+// Ownership test — marker first, command shape as the fallback. The marker is
+// precise but not the only way our entries reach this file: an entry written by
+// a release before the marker existed, or copied by hand from documentation,
+// carries none, and was invisible to BOTH directions here — never deduped on
+// install, never removed on uninstall. Claude's copy of this merge had exactly
+// that gap and it double-fired every lifecycle event (measured live
+// 2026-08-17). Referencing the massa-ai-hook binary is unambiguous; a user hook
+// that merely mentions massa-ai elsewhere does not match.
+const OWNED_COMMAND = /massa-ai-hook/;
+
+function entryIsOwned(e) {
+  if (!e || typeof e !== "object") return false;
+  if (e._massaAiOwned === true) return true;
+  return typeof e.command === "string" && OWNED_COMMAND.test(e.command);
+}
+
 function hasOwned(arr) {
-  return Array.isArray(arr) && arr.some((e) => e && e._massaAiOwned === true);
+  return Array.isArray(arr) && arr.some(entryIsOwned);
 }
 
 if (mode === "uninstall") {
-  for (const [evt] of EVENTS) {
+  // Back up before removing: this now deletes unmarked entries it did not
+  // necessarily write, so the install path's backup discipline applies here too.
+  if (existed) {
+    fs.copyFileSync(file, `${file}.massa-ai.bak-${ts}`);
+  }
+  // Every event, not just the ones this release writes — the predicate
+  // identifies our commands rather than a location.
+  for (const evt of Object.keys(hooks)) {
     if (Array.isArray(hooks[evt])) {
-      hooks[evt] = hooks[evt].filter((e) => !(e && e._massaAiOwned === true));
+      hooks[evt] = hooks[evt].filter((e) => !entryIsOwned(e));
       if (hooks[evt].length === 0) delete hooks[evt];
     }
   }
@@ -325,7 +393,11 @@ install_bundled_skills() {
   fi
 
   local installed=0 name src dest
-  for name in massa-ai persona-router; do
+  # Three harness skills, matching generate-skill-artifacts.ts:138's
+  # authoritative constant (D6/IPT-05) — not derived by scanning the bundle's
+  # skills/ directory, which would install 49 on cursor (every workflow skill
+  # ships as its own directory here).
+  for name in massa-ai persona-router profile; do
     src="$SCRIPT_DIR/skills/$name"
     [[ -d "$src" ]] || continue
     dest="$HARNESS_SKILLS_DIR/$name"
@@ -354,7 +426,7 @@ if (typeof data.platforms !== "object" || data.platforms === null || Array.isArr
 }
 data.version = 2;
 const prev = data.platforms[host];
-data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router"] };
+data.platforms[host] = { root, skillsOwner: "plugin", skills: ["massa-ai", "persona-router", "profile"] };
 // The whole-record replace must not drop fields a previous successful install
 // wrote (R2) — re-attach them. installRoute (T9) is installer-owned but
 // written by a LATER step of this same install (record_plugin_version), so it
@@ -400,7 +472,7 @@ NODE
   )"
   [[ "$raw_owner" == "plugin" ]] && {
     local name
-    for name in massa-ai persona-router; do
+    for name in massa-ai persona-router profile; do
       rm -rf "$HARNESS_SKILLS_DIR/$name"
     done
     rmdir "$HARNESS_SKILLS_DIR" 2>/dev/null || true
@@ -532,97 +604,127 @@ fi
 # ── Install ──────────────────────────────────────────────────────────────────
 # PAU-08/09: bridge-preferred, local-fallback. Computed once, used to decide
 # both which artifacts this run writes and what installRoute gets recorded.
+# Local by default. The probe still runs when the bridge is NOT opted into,
+# purely so the AD-017 double-fire warning below can be accurate — its result
+# no longer decides what gets installed.
 IS_BRIDGE=0
+BRIDGE_AVAILABLE=0
 if claude_bridge_detected; then
-  IS_BRIDGE=1
+  BRIDGE_AVAILABLE=1
+fi
+if [[ "$PREFER_BRIDGE" == "1" ]]; then
+  if [[ "$BRIDGE_AVAILABLE" == "1" ]]; then
+    IS_BRIDGE=1
+    vecho "--prefer-bridge: leaving hook wiring to the Claude bridge."
+  else
+    # Opting into a bridge that is not there would leave the user with no hooks
+    # at all, which is strictly worse than the default. Fall back loudly.
+    echo "  ⚠ --prefer-bridge requested, but ~/.claude does not list massa-ai as installed and enabled." >&2
+    echo "    Falling back to a local hook install so hooks are not silently absent." >&2
+  fi
 fi
 
 skill_count=0
 specialist_count=0
 
 if [[ "$IS_BRIDGE" -eq 1 ]]; then
-  vecho "Installing massa-ai Cursor plugin (Claude-bridge route): ~/.claude already lists massa-ai as installed and enabled, so Cursor loads it via the bridge."
-  # Converge (PAU-08, spec edge case): a pre-existing local install (current
-  # or pre-fix legacy location) must not double-load alongside the bridge, so
-  # one run here ends with exactly one load path. Owned hook entries are
-  # stripped with the SAME filter merge_hooks_json's "uninstall" mode already
-  # uses — the bridge delivers hooks instead.
-  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
-    rm -rf "$LEGACY_PLUGIN_DIR"
-    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
-  fi
-  if [[ -d "$PLUGIN_DIR" ]]; then
-    rm -rf "$PLUGIN_DIR"
-    echo -e "  - removed local plugin copy at $PLUGIN_DIR (Claude bridge already loads massa-ai)"
-  fi
+  vecho "Claude-bridge route: ~/.claude lists massa-ai as installed and enabled, so Cursor delivers its HOOKS via the bridge. The plugin bundle is still installed locally — see below."
+  # Hook wiring, and only hook wiring, is what the bridge actually delivers.
+  # Owned entries are stripped with the SAME filter merge_hooks_json's
+  # "uninstall" mode uses, so the bridge's copy is the only one that fires.
   if [[ -f "$HOOKS_JSON" ]]; then
     merge_hooks_json "$HOOKS_JSON" "uninstall"
     echo -e "  - removed massa-ai hook entries from $HOOKS_JSON (the bridge delivers hooks instead)"
   fi
-else
-  vecho "Installing massa-ai Cursor plugin to: $PLUGIN_DIR"
-  # Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
-  # place risks Cursor discovering both and firing every hook twice, so it goes
-  # before the new location is written.
-  if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
-    rm -rf "$LEGACY_PLUGIN_DIR"
-    echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
-  fi
-  mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks"
-  # Migration: pre-fix installs bundled agents inside the plugin dir, which
-  # Cursor never reads. Drop that copy so upgraders converge on the one real
-  # discovery surface and a future Cursor plugin scan cannot double-register.
-  if [[ -d "$PLUGIN_DIR/agents" ]]; then
-    rm -rf "$PLUGIN_DIR/agents"
-    echo -e "  - removed pre-fix agents copy at $PLUGIN_DIR/agents (Cursor reads $CURSOR_AGENTS_DIR)"
-  fi
+fi
 
-  # Copy manifest
-  cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
-  vecho "  + .cursor-plugin/plugin.json"
-
-  # Copy the host-command skills (each in a subdirectory: skills/<name>/SKILL.md),
-  # quick + generated workflow commands alike. massa-ai/, persona-router/,
-  # agents/, and profile/ are the PDO-06 harness bundle, not a Cursor command
-  # skill — they are installed separately, into the shared harness skills
-  # directory (see "Skills bundling" below), not into this plugin-cache
-  # skills/ tree. `profile` was missing from this exclusion pre-fix, which
-  # leaked it into the command-skill cache mislabeled as `/profile`.
-  for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
-    name="$(basename "$(dirname "$src")")"
-    case "$name" in
-      massa-ai|persona-router|agents|profile) continue ;;
-    esac
-    mkdir -p "$PLUGIN_DIR/skills/$name"
-    cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
-    vecho "  + skills/$name/SKILL.md"
-    skill_count=$((skill_count + 1))
-  done
+# The plugin bundle (manifest + workflow-command skills) installs on BOTH
+# routes. It used to be skipped whenever the bridge was detected, on the
+# premise that the bridge loads the whole plugin.
+#
+# Measured against Cursor 3.16.17 on 2026-08-17, that premise is half true.
+# With the bridge active — massa-ai listed and `enabledPlugins` true in
+# ~/.claude — hooks DO fire in Cursor, while the plugin and its 46 workflow
+# commands are absent from the UI entirely. The old branch therefore deleted a
+# working local bundle and nothing replaced it: the user kept the hooks and
+# silently lost every workflow command. The header's "Cursor 3.14 also bridges
+# the Claude marketplace registry" was pinned against a 2026-08-05 capture and
+# was never re-verified against a later Cursor.
+#
+# So the two deliveries are gated independently: hooks by $IS_BRIDGE above,
+# the bundle never. Reinstating the bundle on the bridge route cannot
+# double-fire hooks — .cursor-plugin/plugin.json declares only
+# name/version/description, so the bundle carries no hook wiring of its own;
+# $HOOKS_JSON is the only surface that does, and on the bridge route it is
+# left stripped.
+vecho "Installing the massa-ai Cursor plugin bundle to: $PLUGIN_DIR"
+# Migration: a pre-fix install left a copy at plugins/massa-ai. Leaving it in
+# place risks Cursor discovering both and firing every hook twice, so it goes
+# before the new location is written. Runs on both routes.
+if [[ -d "$LEGACY_PLUGIN_DIR" ]]; then
+  rm -rf "$LEGACY_PLUGIN_DIR"
+  echo -e "  - removed pre-fix plugin copy at $LEGACY_PLUGIN_DIR"
+fi
+mkdir -p "$PLUGIN_DIR/.cursor-plugin" "$PLUGIN_DIR/skills" "$PLUGIN_DIR/hooks"
+# Migration: pre-fix installs bundled agents inside the plugin dir, which
+# Cursor never reads. Drop that copy so upgraders converge on the one real
+# discovery surface and a future Cursor plugin scan cannot double-register.
+if [[ -d "$PLUGIN_DIR/agents" ]]; then
+  rm -rf "$PLUGIN_DIR/agents"
+  echo -e "  - removed pre-fix agents copy at $PLUGIN_DIR/agents (Cursor reads $CURSOR_AGENTS_DIR)"
+fi
 
-  # Copy hooks.json (the placeholder version — installer replaces paths)
-  cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
-  vecho "  + hooks/hooks.json"
-
-  # Older installs shipped a plugin-local mcp.json here. Cursor reads
-  # ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
-  # scripts/install-agents.sh — drop the residue so upgraders converge.
-  if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
-    rm -f "$PLUGIN_DIR/mcp.json"
-    # Not gated by --quiet: this deletes a file in the user's home, so it is a
-    # mutation notice rather than per-file chatter.
-    echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
-  fi
+# Copy manifest
+cp "$SCRIPT_DIR/.cursor-plugin/plugin.json" "$PLUGIN_DIR/.cursor-plugin/plugin.json"
+vecho "  + .cursor-plugin/plugin.json"
+
+# Copy the host-command skills (each in a subdirectory: skills/<name>/SKILL.md),
+# quick + generated workflow commands alike. massa-ai/, persona-router/,
+# agents/, and profile/ are the PDO-06 harness bundle, not a Cursor command
+# skill — they are installed separately, into the shared harness skills
+# directory (see "Skills bundling" below), not into this plugin-cache
+# skills/ tree. `profile` was missing from this exclusion pre-fix, which
+# leaked it into the command-skill cache mislabeled as `/profile`.
+for src in "$SCRIPT_DIR/skills/"*/SKILL.md; do
+  name="$(basename "$(dirname "$src")")"
+  case "$name" in
+    massa-ai|persona-router|agents|profile) continue ;;
+  esac
+  mkdir -p "$PLUGIN_DIR/skills/$name"
+  cp "$src" "$PLUGIN_DIR/skills/$name/SKILL.md"
+  vecho "  + skills/$name/SKILL.md"
+  skill_count=$((skill_count + 1))
+done
+
+# Copy hooks.json (the placeholder version — installer replaces paths)
+cp "$SCRIPT_DIR/hooks/hooks.json" "$PLUGIN_DIR/hooks/hooks.json"
+vecho "  + hooks/hooks.json"
+
+# Older installs shipped a plugin-local mcp.json here. Cursor reads
+# ~/.cursor/mcp.json, not the plugin dir, and MCP is now owned by
+# scripts/install-agents.sh — drop the residue so upgraders converge.
+if [[ -f "$PLUGIN_DIR/mcp.json" ]]; then
+  rm -f "$PLUGIN_DIR/mcp.json"
+  # Not gated by --quiet: this deletes a file in the user's home, so it is a
+  # mutation notice rather than per-file chatter.
+  echo -e "  - removed stale mcp.json (MCP is now registered in ~/.cursor/mcp.json)"
 fi
 
 # Flat agents and harness skills are written in BOTH branches (PAU-08/09):
 # Cursor discovers subagents only from the flat directory regardless of which
 # plugin-load path is active, and MCP/harness-skills ownership is independent
-# of it too. Prune-then-copy so a specialist deleted from the bundle cannot
-# linger installed. All of them, navigator included, are generated from
+# of it too. All of them, navigator included, are generated from
 # skills/agents/*/SKILL.md and owned by the massa-ai- name prefix (CRS-04) —
 # user-authored agents are untouched.
+#
+# Copy-then-prune (D1/IPT-02 AC-02.6), not prune-then-copy: this loop copies
+# the current set first, and only afterward sheds destination entries the
+# bundle no longer ships. `set -euo pipefail` is in force, so a mid-loop `cp`
+# failure aborts the script — under the old prune-first order that left the
+# user with fewer agents than before the upgrade (possibly none); under this
+# order the worst case is a retired agent lingering one run longer, which is
+# the pre-fix status quo this feature already tolerates.
 mkdir -p "$CURSOR_AGENTS_DIR"
-rm -f "$CURSOR_AGENTS_DIR/"massa-ai-*.md
 for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
   [[ -f "$src" ]] || continue
   name="$(basename "$src")"
@@ -632,6 +734,19 @@ for src in "$SCRIPT_DIR/agents/"massa-ai-*.md; do
 done
 vecho "  + ${specialist_count} subagent specialists (generated from skills/agents/*/SKILL.md)"
 
+# Shed owned members the bundle no longer ships (D2): the removal population
+# is the destination directory; the bundle supplies only the keep-predicate.
+# Loop over the destination, consult the bundle only to decide whether to
+# keep — never loop over the bundle to decide removals. Ownership test is the
+# massa-ai- name prefix (D3), same as the uninstall loop above.
+for f in "$CURSOR_AGENTS_DIR/"massa-ai-*.md; do
+  [[ -f "$f" ]] || continue
+  name="$(basename "$f")"
+  [[ -f "$SCRIPT_DIR/agents/$name" ]] && continue   # keep-list: still shipped
+  rm -f "$f"
+  vecho "  - $name (retired, no longer shipped)"
+done
+
 # Skills bundling (PDO-08, 09): install massa-ai/persona-router into the
 # shared harness skills directory, unless scripts/install-skills.sh already
 # owns it for this platform. Runs in both branches (same reasoning as above).
@@ -685,9 +800,20 @@ fi
 # Summary line in quiet mode
 if [ "${MASSA_AI_VERBOSE:-0}" != "1" ]; then
   if [[ "$IS_BRIDGE" -eq 1 ]]; then
-    ok "cursor plugin: using the Claude bridge (${specialist_count} specialists) — hooks delivered by the bridge, not installed locally"
+    ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists) — hooks left to the Claude bridge (--prefer-bridge)"
+    ok "  if massa-ai hooks do NOT fire in Cursor, the bridge is not delivering them: re-run without --prefer-bridge"
   else
     ok "cursor plugin installed (${skill_count} skills, ${specialist_count} specialists, 7 hooks)"
+    if [[ "$BRIDGE_AVAILABLE" -eq 1 ]]; then
+      # AD-017: both sources live. Not an error — the default is local by
+      # design — but the user must be told, because a doubled hook is silent
+      # and looks like the tool misbehaving rather than being installed twice.
+      echo "  ⚠ ~/.claude also lists massa-ai as installed and enabled." >&2
+      echo "    If Cursor's Claude bridge delivers those hooks, they now fire TWICE" >&2
+      echo "    (once from the bridge, once from ~/.cursor/hooks.json)." >&2
+      echo "    Keep one source: re-run with --prefer-bridge, or disable massa-ai" >&2
+      echo "    in ~/.claude/settings.json (enabledPlugins)." >&2
+    fi
   fi
 else
   vecho ""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@massa-ai/cursor-plugin",
-  "version": "1.52.0",
+  "version": "1.54.1",
   "description": "massa-ai plugin for Cursor — semantic code search, memory, and context compression",
   "files": [
     "agents",

package/skills/massa-ai/SKILL.md

@@ -46,7 +46,7 @@ Before reading any massa-ai file:
   Never pass `workflowSessionId` in that field. Use `synapse_task_begin`/`synapse_task_end`
   for task envelopes and `synapse_prefetch` to warm the buffer on file open.
 - Prefer the shared v2 retrieval order; fall back gracefully if the massa-ai
-  server or Synapse is unavailable. The full tool surface includes 54 tools
+  server or Synapse is unavailable. The full tool surface includes 59 tools
   (see `references/mcp-tools.md`): indexing, search, symbol graph
   (`trace_path`, `impact_analysis`, `get_architecture`), memory CRUD
   (`remember`, `recall`, `memory_update`, `memory_delete`), checkpoints

package/skills/massa-ai/references/mcp-tools.md

@@ -1,4 +1,4 @@
-# massa-ai Tool Contracts (54 Tools)
+# massa-ai Tool Contracts (59 Tools)
 
 Load when exact MCP schemas, REST fallbacks, response modes, or
 polling rules are needed. Prefer the active tool declaration over copied
@@ -103,6 +103,8 @@ depends on exact content.
 | `handoff_accept` | Accept an open handoff (open→accepted) | Req: `id`. Opt: `projectId`. |
 | `handoff_cancel` | Cancel/expire an open handoff | Req: `id`. Opt: `projectId`. |
 | `handoff_list_pending` | List open handoffs, oldest-first | Req: `projectId`. Opt: `targetAgent`. |
+| `handoff_update` | Edit targetAgent/summary/openQuestions/nextSteps/files by id | Req: `id`. Opt: `projectId`, `targetAgent`, `summary`, `openQuestions`, `nextSteps`, `files` — at least one editable field required. Unknown/restricted fields (`status`, `acceptedAt`, etc.) are rejected by name. |
+| `handoff_delete` | Hard-delete a handoff, any status | Req: `id`. Opt: `projectId`. |
 
 ## MCP Capability Matrix — Auto-improvement (Proposals)
 
@@ -111,6 +113,9 @@ depends on exact content.
 | `list_proposals` | List pending auto-improvement proposals, newest-first | Req: `projectId`. |
 | `approve_proposal` | Approve a proposal; applies the memory edit | Req: `id`. Opt: `projectId`, `source`. |
 | `reject_proposal` | Reject a proposal (no edit applied) | Req: `id`. Opt: `projectId`, `reason`. |
+| `create_proposal` | Create a pending proposal by hand | Req: `projectId`, `kind` (`memory.create`\|`memory.update`\|`memory.tag`), `payload`. Opt: `rationale`, `targetMemoryId`. `payload` is validated against the same per-kind rules the store enforces on read. |
+| `update_proposal` | Edit rationale/payload by id, any status | Req: `id`. Opt: `projectId`, `rationale`, `payload` — at least one editable field required. `kind`/`targetMemoryId`/`status`/`decidedAt` are immutable. A `payload` edit re-validates against the row's existing `kind`. |
+| `delete_proposal` | Hard-delete a proposal, any status | Req: `id`. Opt: `projectId`. Deleting an approved proposal does not reverse its applied memory edit. |
 
 ## MCP Capability Matrix — Passive Capture