@openparachute/agent 0.1.1 → 0.1.2

package/src/config.ts

@@ -12,9 +12,20 @@ export const ASSISTANT_NAME = process.env.ASSISTANT_NAME || envConfig.ASSISTANT_
 export const ASSISTANT_HAS_OWN_NUMBER =
   (process.env.ASSISTANT_HAS_OWN_NUMBER || envConfig.ASSISTANT_HAS_OWN_NUMBER) === 'true';
 
-// Absolute paths needed for container mounts
-const PROJECT_ROOT = process.cwd();
-const HOME_DIR = process.env.HOME || os.homedir();
+// Absolute paths needed for container mounts. Captured once at module load
+// (process.cwd() at boot — the right value for the install dir) so every
+// downstream consumer agrees on a single resolved root, and tests that
+// chdir() can't desync against it. Exported for surfaces that need to
+// self-register the install path (e.g. services.json `installDir`,
+// paraclaw#115).
+export const PROJECT_ROOT = process.cwd();
+// Operator's home dir. Resolved once at module load — every downstream
+// consumer that needs to expand `~` or derive a HOME-relative path imports
+// this rather than calling `os.homedir()` itself, so a future precedence
+// change (e.g. add a `PARACHUTE_AGENT_HOME` override) is one edit. Honors
+// `HOME` env var first (sandbox-friendly, matches POSIX convention) before
+// falling back to the real home dir.
+export const HOME_DIR = process.env.HOME || os.homedir();
 
 // Parachute ecosystem root. Convention shared with parachute-hub, vault,
 // scribe — every module's persistent state lands under this directory
@@ -28,6 +39,15 @@ export const PARACHUTE_DIR = process.env.PARACHUTE_HOME || path.join(HOME_DIR, '
 // pre-existing files from the legacy dir on first 0.1.0 boot. The legacy
 // constants are exported for the migration to consult; nothing else should
 // read them. Drop in 0.2.0.
+//
+// Note (paraclaw#99): the allowlist sits at `<HOME>/.config/parachute-agent/`,
+// NOT under `PARACHUTE_DIR`. This is intentional — the file is operator-host
+// policy ("which paths can the agent ever mount on this host"), not runtime
+// state of any one install. Two installs sharing a host should agree on the
+// allowlist; a sandbox at `PARACHUTE_HOME=/tmp/sandbox` deliberately reads
+// the same file the live install does. Runtime state (central DB +
+// master.key) routes through `PARACHUTE_DIR` instead — see CENTRAL_DB_DIR
+// below and the sandbox-isolation block in CLAUDE.md.
 export const ALLOWLIST_DIR = path.join(HOME_DIR, '.config', 'parachute-agent');
 export const LEGACY_ALLOWLIST_DIR = path.join(HOME_DIR, '.config', 'paraclaw');
 export const MOUNT_ALLOWLIST_PATH = path.join(ALLOWLIST_DIR, 'mount-allowlist.json');

package/src/container-runtime.test.ts

@@ -22,9 +22,10 @@ import {
   readonlyMountArgs,
   stopContainer,
   ensureContainerRuntimeRunning,
+  ensureContainerImage,
   cleanupOrphans,
 } from './container-runtime.js';
-import { CONTAINER_INSTALL_LABEL, LEGACY_PARACLAW_INSTALL_LABEL } from './config.js';
+import { CONTAINER_IMAGE, CONTAINER_INSTALL_LABEL, LEGACY_PARACLAW_INSTALL_LABEL } from './config.js';
 import { log } from './log.js';
 
 beforeEach(() => {
@@ -82,6 +83,105 @@ describe('ensureContainerRuntimeRunning', () => {
   });
 });
 
+// --- ensureContainerImage ---
+
+describe('ensureContainerImage', () => {
+  // Each test enumerates its own queue rather than going through a helper —
+  // throwing scenarios skip the retag call, so a generic helper would queue
+  // a `mockReturnValueOnce` that never gets consumed and leaks into the next
+  // test (vi.clearAllMocks doesn't drain the response queue).
+  const inspectFailed = () => {
+    mockExecSync.mockImplementationOnce(() => {
+      throw new Error('No such image');
+    });
+  };
+
+  it('no-ops when the expected image is already present', () => {
+    mockExecSync.mockReturnValueOnce('{}'); // inspect — image exists
+
+    ensureContainerImage();
+
+    expect(mockExecSync).toHaveBeenCalledTimes(1);
+    expect(mockExecSync).toHaveBeenCalledWith(
+      `${CONTAINER_RUNTIME_BIN} image inspect ${CONTAINER_IMAGE}`,
+      expect.objectContaining({ stdio: 'pipe' }),
+    );
+    expect(log.warn).not.toHaveBeenCalled();
+  });
+
+  it('retags from a current-prefix peer when the expected image is missing', () => {
+    // Operator dir-rename case: the previously-built image carries the old
+    // INSTALL_SLUG (cafef00d); the daemon now boots under a new slug.
+    const peer = 'parachute-agent-image-cafef00d:latest';
+    inspectFailed();
+    mockExecSync.mockReturnValueOnce(`${peer}\nnode:24-bookworm-slim\n`); // list
+    mockExecSync.mockReturnValueOnce(''); // tag
+
+    ensureContainerImage();
+
+    expect(mockExecSync).toHaveBeenCalledTimes(3);
+    expect(mockExecSync).toHaveBeenNthCalledWith(
+      3,
+      `${CONTAINER_RUNTIME_BIN} tag ${peer} ${CONTAINER_IMAGE}`,
+      expect.objectContaining({ stdio: 'pipe' }),
+    );
+    expect(log.warn).toHaveBeenCalledWith(
+      'Container image missing for current install slug — retagging from peer',
+      expect.objectContaining({ expected: CONTAINER_IMAGE, peer }),
+    );
+  });
+
+  it('retags from a pre-0.1.0 paraclaw-agent peer (one cycle of back-compat)', () => {
+    // Operator upgrades a pre-0.1.0 install: their on-disk image is named
+    // `paraclaw-agent-<slug>:latest`. Auto-retag rather than forcing a
+    // 5-minute rebuild they didn't ask for.
+    const legacyPeer = 'paraclaw-agent-cafef00d:latest';
+    inspectFailed();
+    mockExecSync.mockReturnValueOnce(legacyPeer);
+    mockExecSync.mockReturnValueOnce('');
+
+    ensureContainerImage();
+
+    expect(mockExecSync).toHaveBeenNthCalledWith(
+      3,
+      `${CONTAINER_RUNTIME_BIN} tag ${legacyPeer} ${CONTAINER_IMAGE}`,
+      expect.objectContaining({ stdio: 'pipe' }),
+    );
+  });
+
+  it('throws an actionable error when no peer exists (fresh install, no build yet)', () => {
+    // No matching prefix on disk: only unrelated base images. Better to fail
+    // visibly at startup than crashloop code=125 on every container spawn.
+    inspectFailed();
+    mockExecSync.mockReturnValueOnce('node:24-bookworm-slim\nubuntu:22.04\n');
+
+    expect(() => ensureContainerImage()).toThrow(/build\.sh/);
+    expect(mockExecSync).toHaveBeenCalledTimes(2); // inspect + list, no tag
+  });
+
+  it('skips the (missing) expected name when picking a peer from the listing', () => {
+    // Belt-and-suspenders: the inspect already confirmed the expected name
+    // is absent, but the peer-search guard against picking it back up keeps
+    // the function safe if a future caller pre-checks a different way.
+    inspectFailed();
+    mockExecSync.mockReturnValueOnce(`${CONTAINER_IMAGE}\nparachute-agent-image-cafef00d:latest\n`);
+    mockExecSync.mockReturnValueOnce('');
+
+    ensureContainerImage();
+
+    const tagCall = mockExecSync.mock.calls.find((call) => String(call[0]).startsWith(`${CONTAINER_RUNTIME_BIN} tag`));
+    expect(tagCall).toBeDefined();
+    expect(String(tagCall![0])).toContain('parachute-agent-image-cafef00d:latest');
+  });
+
+  it('ignores arbitrary non-matching tags (e.g. base images, unrelated projects)', () => {
+    inspectFailed();
+    mockExecSync.mockReturnValueOnce('node:24-bookworm-slim\nparachute-vault:latest\nrandomthing:v2\n');
+
+    expect(() => ensureContainerImage()).toThrow(/build\.sh/);
+  });
+});
+
 // --- cleanupOrphans ---
 
 describe('cleanupOrphans', () => {

package/src/container-runtime.ts

@@ -5,9 +5,19 @@
 import { execSync } from 'child_process';
 import os from 'os';
 
-import { CONTAINER_INSTALL_LABEL, LEGACY_PARACLAW_INSTALL_LABEL } from './config.js';
+import { CONTAINER_IMAGE, CONTAINER_INSTALL_LABEL, LEGACY_PARACLAW_INSTALL_LABEL } from './config.js';
 import { log } from './log.js';
 
+// Per-install image tag schemas:
+//   - 0.1.0+:    `parachute-agent-image-<8-hex-slug>:latest`
+//   - pre-0.1.0: `paraclaw-agent-<8-hex-slug>:latest` (kept for one cycle of
+//                back-compat so an operator who upgrades into a 0.1.x checkout
+//                without rebuilding the image still gets a working spawn;
+//                drop in 0.2.0 — same lifecycle as LEGACY_PARACLAW_INSTALL_LABEL).
+// Both prefixes are stable + content-equivalent — Dockerfile baseline
+// matches across slugs — so a `docker tag` of any peer is safe.
+const PEER_IMAGE_PATTERN = /^(parachute-agent-image|paraclaw-agent)-[0-9a-f]{8}:latest$/;
+
 /** The container runtime binary name. */
 export const CONTAINER_RUNTIME_BIN = 'docker';
 
@@ -57,6 +67,71 @@ export function ensureContainerRuntimeRunning(): void {
   }
 }
 
+/**
+ * Ensure the per-install container image is reachable before we start
+ * spawning sessions.
+ *
+ * INSTALL_SLUG = sha1(process.cwd())[:8], so an operator dir-rename
+ * (paraclaw#114) flips the slug. The previously-built image carries the
+ * OLD slug; the daemon goes to spawn against the NEW slug; `docker run`
+ * returns code=125 ("image not found") and every container spawn
+ * crashloops silently.
+ *
+ * Resolution path, ordered fail-fast → cheap → loud:
+ *   1. Expected tag present → no-op.
+ *   2. Any peer image (`parachute-agent-image-*` or pre-0.1.0
+ *      `paraclaw-agent-*`) present → `docker tag` it to the expected
+ *      name. Safe because the Dockerfile baseline doesn't fork per slug.
+ *   3. No peer found → throw with an actionable hint. The daemon was
+ *      going to crashloop anyway; failing visibly at startup is strictly
+ *      better than silent code=125 on every Telegram message.
+ */
+export function ensureContainerImage(): void {
+  if (imageExists(CONTAINER_IMAGE)) {
+    log.debug('Container image present', { image: CONTAINER_IMAGE });
+    return;
+  }
+  const peer = findPeerImage(CONTAINER_IMAGE);
+  if (peer) {
+    // The dir-rename / upgrade case. Loud-warn so the operator can see in
+    // the log what happened — silent retags become folklore.
+    log.warn('Container image missing for current install slug — retagging from peer', {
+      expected: CONTAINER_IMAGE,
+      peer,
+      hint: 'Operator dir-rename or upgrade likely changed INSTALL_SLUG. Auto-retagging is safe; rebuild via ./container/build.sh next time you want to refresh dependencies.',
+    });
+    execSync(`${CONTAINER_RUNTIME_BIN} tag ${peer} ${CONTAINER_IMAGE}`, { stdio: 'pipe' });
+    return;
+  }
+  throw new Error(
+    `No parachute-agent container image found. Build one with: ./container/build.sh\n` +
+      `Expected image: ${CONTAINER_IMAGE}`,
+  );
+}
+
+function imageExists(ref: string): boolean {
+  try {
+    execSync(`${CONTAINER_RUNTIME_BIN} image inspect ${ref}`, { stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function findPeerImage(exclude: string): string | null {
+  const output = execSync(`${CONTAINER_RUNTIME_BIN} images --format '{{.Repository}}:{{.Tag}}'`, {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    encoding: 'utf-8',
+  });
+  // `docker images` lists newest-created first by default. Take the first
+  // matching peer so a recent rebuild wins over a stale legacy tag.
+  for (const ref of output.trim().split('\n').filter(Boolean)) {
+    if (ref === exclude) continue;
+    if (PEER_IMAGE_PATTERN.test(ref)) return ref;
+  }
+  return null;
+}
+
 /**
  * Kill orphaned parachute-agent containers from THIS install's previous runs.
  *

package/src/db/connection.migrate.test.ts

@@ -13,6 +13,7 @@ import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { migrateCentralDbLocation, migrateMasterKeyLocation } from './connection.js';
+import { log } from '../log.js';
 
 let tmp: string;
 let legacy: string;
@@ -129,15 +130,47 @@ describe('migrateMasterKeyLocation', () => {
     }
   });
 
-  it('current key already exists — legacy left untouched (no clobber)', () => {
+  it('current key already exists, no legacy — noop (already migrated, or fresh install)', () => {
+    mkdirSync(currentDir, { recursive: true });
+    writeFileSync(currentKey, 'new-key-bytes-padding-to-32-aaaa');
+
+    migrateMasterKeyLocation(legacyDir, currentDir);
+
+    expect(readFileSync(currentKey, 'utf8')).toBe('new-key-bytes-padding-to-32-aaaa');
+    expect(existsSync(legacyKey)).toBe(false);
+  });
+
+  it('both keys exist — log a warn with recovery hint, leave both untouched', () => {
+    // Regression for parachute-agent#114: a previous boot generated a fresh
+    // key at the new path before the legacy was copied, so encrypted-secret
+    // rows sealed under the legacy key are now undecryptable. Don't
+    // clobber — surface it loudly so the operator can choose how to recover.
     mkdirSync(legacyDir, { recursive: true });
     writeFileSync(legacyKey, 'old-key-bytes-padding-to-32-aaaa');
     mkdirSync(currentDir, { recursive: true });
     writeFileSync(currentKey, 'new-key-bytes-padding-to-32-aaaa');
 
-    migrateMasterKeyLocation(legacyDir, currentDir);
+    const original = log.warn;
+    const calls: Array<[string, Record<string, unknown> | undefined]> = [];
+    log.warn = ((msg: string, data?: Record<string, unknown>) => {
+      calls.push([msg, data]);
+    }) as typeof log.warn;
+    try {
+      migrateMasterKeyLocation(legacyDir, currentDir);
+    } finally {
+      log.warn = original;
+    }
 
     expect(readFileSync(currentKey, 'utf8')).toBe('new-key-bytes-padding-to-32-aaaa');
     expect(readFileSync(legacyKey, 'utf8')).toBe('old-key-bytes-padding-to-32-aaaa');
+    expect(calls).toHaveLength(1);
+    const [msg, ctx] = calls[0]!;
+    expect(msg).toMatch(/both/i);
+    const ctxObj = ctx as { legacy: string; current: string; note: string };
+    expect(ctxObj.legacy).toBe(legacyKey);
+    expect(ctxObj.current).toBe(currentKey);
+    // Recovery hint must name both paths so an operator can copy/paste it.
+    expect(ctxObj.note).toContain(legacyKey);
+    expect(ctxObj.note).toContain(currentKey);
   });
 });

package/src/db/connection.ts

@@ -67,10 +67,29 @@ export function migrateCentralDbLocation(
  * One-shot migration: copy `<PARACHUTE_DIR>/claw/master.key` to
  * `<PARACHUTE_DIR>/agent/master.key` so encrypted-secret rows decrypted under
  * the old key continue to decrypt after the paraclaw → parachute-agent
- * rename. Idempotent — noop if the new key already exists OR the legacy
- * key doesn't.
+ * rename. Idempotent.
  *
- * The legacy file is left in place — same rationale as the DB migration.
+ * Three cases:
+ *   1. Only legacy exists  → copy to current, chmod 0600. Legacy stays as
+ *      backup (operators verify and rm manually — same rationale as the DB).
+ *   2. Both exist          → log a `warn` with both paths and a recovery
+ *      hint, then noop. This is the silent-corruption bug from
+ *      `parachute-agent#114`: a previous boot generated a fresh key at the
+ *      new path before the legacy was copied, so the new key can't decrypt
+ *      the operator's existing secret rows. Don't overwrite — a partial
+ *      restore would lose secrets that were re-encrypted under the fresh
+ *      key. Surface it loudly so the operator can choose.
+ *   3. Neither exists      → noop (fresh install).
+ *   4. Only current exists → noop (already migrated, or fresh install where
+ *      first boot created the key directly at the new path).
+ *
+ * MUST run before any caller of `loadOrCreateMasterKey()`. That function
+ * generates a fresh 32-byte key at the new path on first miss, which would
+ * shadow the legacy and trip case 2 on the next boot. `src/index.ts:main`
+ * calls this immediately after `migrateCentralDbLocation`. Standalone
+ * scripts (init-cli-agent, init-first-agent, seed-discord) call it for
+ * the same reason: any path that may end up touching the secrets store
+ * needs the legacy in place first.
  *
  * Path overrides exist for tests; production callers pass no args.
  */
@@ -80,8 +99,24 @@ export function migrateMasterKeyLocation(
 ): void {
   const legacyKey = path.join(legacyDir, 'master.key');
   const currentKey = path.join(currentDir, 'master.key');
-  if (fs.existsSync(currentKey)) return;
-  if (!fs.existsSync(legacyKey)) return;
+  const legacyExists = fs.existsSync(legacyKey);
+  const currentExists = fs.existsSync(currentKey);
+
+  if (currentExists && legacyExists) {
+    log.warn('Master key exists at both new and legacy locations', {
+      legacy: legacyKey,
+      current: currentKey,
+      note:
+        'this means an earlier boot created a fresh key at the new path before the legacy was copied; ' +
+        `existing encrypted secrets were sealed under the legacy key and the fresh key cannot decrypt them. ` +
+        `If you have NOT yet entered new secrets under the fresh key, recover with: ` +
+        `mv ${currentKey} ${currentKey}.fresh-backup && cp ${legacyKey} ${currentKey} && chmod 600 ${currentKey}. ` +
+        `If you HAVE entered new secrets, the two are now mixed and you must re-enter the legacy ones manually.`,
+    });
+    return;
+  }
+  if (currentExists) return;
+  if (!legacyExists) return;
 
   fs.mkdirSync(currentDir, { recursive: true, mode: 0o700 });
   fs.copyFileSync(legacyKey, currentKey);

package/src/index.ts

@@ -10,7 +10,7 @@ import { CENTRAL_DB_PATH } from './config.js';
 import { migrateGroupsToClaudeLocal } from './claude-md-compose.js';
 import { initDb, migrateCentralDbLocation, migrateMasterKeyLocation } from './db/connection.js';
 import { runMigrations } from './db/migrations/index.js';
-import { ensureContainerRuntimeRunning, cleanupOrphans } from './container-runtime.js';
+import { ensureContainerRuntimeRunning, ensureContainerImage, cleanupOrphans } from './container-runtime.js';
 import { startActiveDeliveryPoll, startSweepDeliveryPoll, setDeliveryAdapter, stopDeliveryPolls } from './delivery.js';
 import { startHostSweep, stopHostSweep } from './host-sweep.js';
 import { routeInbound } from './router.js';
@@ -89,6 +89,11 @@ async function main(): Promise<void> {
 
   // 2. Container runtime
   ensureContainerRuntimeRunning();
+  // Auto-retag the per-install image when an operator dir-rename has flipped
+  // INSTALL_SLUG out from under a previously-built image (paraclaw#114).
+  // Throws with an actionable hint when no image at all is on disk — better
+  // than the silent code=125 crashloop the daemon used to fall into.
+  ensureContainerImage();
   cleanupOrphans();
 
   // 3. Channel adapters

package/src/mcp/tools/channels.test.ts

@@ -0,0 +1,126 @@
+/**
+ * MCP-path coverage for `update-channel-wire`. The MCP SDK does not enforce
+ * a tool's `inputSchema` against `tools/call` arguments before dispatching
+ * to the handler (see comment on `ToolDef.inputSchema` in src/mcp/types.ts),
+ * so the handler must defensively gate enum-typed fields itself. Without
+ * the gate, a stale-schema client (cached pre-rc.6 senderScope vocabulary,
+ * or a hand-rolled call) would fall through the if/else patch-construction
+ * and silently no-op the column update — exactly the silent-coerce class
+ * paraclaw#94 set out to close.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { closeDb, initTestDb, runMigrations } from '../../db/index.js';
+import { createAgentGroup } from '../../db/agent-groups.js';
+import {
+  createMessagingGroup,
+  createMessagingGroupAgent,
+  getMessagingGroupAgent,
+} from '../../db/messaging-groups.js';
+import type { ToolHandlerContext } from '../types.js';
+import { channelTools } from './channels.js';
+
+const updateTool = channelTools.find((t) => t.name === 'update-channel-wire')!;
+
+const ctx: ToolHandlerContext = { effectiveScope: 'agent:admin', callerSubject: 'mcp:stdio' };
+
+const now = (): string => new Date().toISOString();
+
+function seedWire(over: { sender_scope?: 'all' | 'known' } = {}): void {
+  createAgentGroup({
+    id: 'ag_mcp',
+    name: 'MCP test',
+    folder: 'mcp-test',
+    agent_provider: null,
+    secret_mode: 'all',
+    created_at: now(),
+  });
+  createMessagingGroup({
+    id: 'mg_mcp',
+    channel_type: 'telegram',
+    platform_id: 'telegram:99:88',
+    name: null,
+    is_group: 0,
+    unknown_sender_policy: 'request_approval',
+    created_at: now(),
+  });
+  createMessagingGroupAgent({
+    id: 'mga_mcp',
+    messaging_group_id: 'mg_mcp',
+    agent_group_id: 'ag_mcp',
+    engage_mode: 'mention',
+    engage_pattern: null,
+    sender_scope: over.sender_scope ?? 'known',
+    ignored_message_policy: 'drop',
+    session_mode: 'shared',
+    priority: 0,
+    created_at: now(),
+  });
+}
+
+beforeEach(() => {
+  const db = initTestDb();
+  runMigrations(db);
+});
+
+afterEach(() => {
+  closeDb();
+});
+
+describe('mcp update-channel-wire — paraclaw#94 senderScope vocabulary', () => {
+  it("round-trips senderScope='unrestricted' → DB sender_scope='all' → response 'unrestricted'", async () => {
+    seedWire({ sender_scope: 'known' });
+
+    const result = (await updateTool.handler({ id: 'mga_mcp', senderScope: 'unrestricted' }, ctx)) as {
+      wire: { senderScope: string };
+    };
+
+    expect(result.wire.senderScope).toBe('unrestricted');
+    expect(getMessagingGroupAgent('mga_mcp')!.sender_scope).toBe('all');
+  });
+
+  it("rejects the legacy wire literal senderScope='all' instead of silent no-op", async () => {
+    // The bug shape: pre-fix, the handler's if/else pair only matched
+    // 'allowlist' and 'unrestricted'; legacy 'all' fell through and
+    // `patch.sender_scope` was never assigned, so updateMessagingGroupAgent
+    // ran with no sender_scope key and the column kept its previous value
+    // — server returned success, client believed the field changed,
+    // operator saw no error. Pin that the gate now refuses it.
+    seedWire({ sender_scope: 'known' });
+
+    await expect(updateTool.handler({ id: 'mga_mcp', senderScope: 'all' }, ctx)).rejects.toThrow(
+      /invalid senderScope: all/,
+    );
+
+    // And critically — the column was NOT silently mutated.
+    expect(getMessagingGroupAgent('mga_mcp')!.sender_scope).toBe('known');
+  });
+
+  it("rejects the legacy DB-side literal ignoredMessagePolicy='accumulate'", async () => {
+    // Same silent-coerce class on a sibling field — the DB stores
+    // 'accumulate' but the wire vocabulary is 'silent'. Pre-gate, sending
+    // 'accumulate' on the wire fell through both if-branches.
+    seedWire();
+
+    await expect(
+      updateTool.handler({ id: 'mga_mcp', ignoredMessagePolicy: 'accumulate' }, ctx),
+    ).rejects.toThrow(/invalid ignoredMessagePolicy: accumulate/);
+
+    expect(getMessagingGroupAgent('mga_mcp')!.ignored_message_policy).toBe('drop');
+  });
+
+  it('rejects an unknown engageMode instead of silent no-op via the engagePattern fallback', async () => {
+    // engageMode's if/else chain has a fourth branch that fires when the
+    // mode is unrecognized but engagePattern is present — so a typo'd
+    // engageMode used to silently update only the pattern. Pin the gate.
+    seedWire();
+
+    await expect(
+      updateTool.handler({ id: 'mga_mcp', engageMode: 'wave-hands', engagePattern: 'whatever' }, ctx),
+    ).rejects.toThrow(/invalid engageMode: wave-hands/);
+
+    const persisted = getMessagingGroupAgent('mga_mcp')!;
+    expect(persisted.engage_mode).toBe('mention');
+    expect(persisted.engage_pattern).toBeNull();
+  });
+});