@openparachute/agent 0.1.0 → 0.1.2

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();
+  });
+});

package/src/mcp/tools/channels.ts

@@ -1,13 +1,25 @@
 /**
- * MCP tools for channel-wire CRUD. Mirrors `/api/channels`. The DB still
- * stores the pre-rebuild enum names (engage_mode = mention | pattern |
- * mention-sticky; sender_scope = all | known; ignored_message_policy = drop
- * | accumulate); the API contract these tools speak — same as the web API —
- * uses the new vocabulary (engageMode = mention | pattern | all; senderScope
- * = allowlist | all; ignoredMessagePolicy = drop | silent). The translator
- * is small so we inline it here rather than carving out a shared module
- * that would need its own seam through the route handler.
+ * MCP tools for channel-wire CRUD. Mirrors `/api/channels`.
+ *
+ * The wire-shape <-> DB-shape translator + patch validator now live in
+ * `src/channels/api-translator.ts` (paraclaw#123) and are shared with the
+ * HTTP route. See that module for the enum translation contract; this
+ * file owns the MCP tool plumbing only.
+ *
+ * The MCP SDK does NOT enforce `inputSchema` against `tools/call` args
+ * before dispatch (see ToolDef.inputSchema in src/mcp/types.ts), so the
+ * shared `validatePatchInput` doubles as the defensive gate this handler
+ * relied on inline before. paraclaw#94 / PR #122 closed the same
+ * silent-coerce class on the HTTP side; #123 brings the MCP side onto
+ * the same canonical validator.
  */
+import {
+  apiToDbPatch,
+  type ChannelWireView,
+  rowToView,
+  validatePatchInput,
+  type WireJoinRow,
+} from '../../channels/api-translator.js';
 import { getAgentGroup } from '../../db/agent-groups.js';
 import { getDb } from '../../db/connection.js';
 import {
@@ -16,79 +28,12 @@ import {
   getMessagingGroupAgent,
   updateMessagingGroupAgent,
 } from '../../db/messaging-groups.js';
-import type {
-  EngageMode as DbEngageMode,
-  IgnoredMessagePolicy as DbIgnoredMessagePolicy,
-  SenderScope as DbSenderScope,
-  MessagingGroupAgent,
-} from '../../types.js';
 import type { ToolDef } from '../types.js';
 
-type ApiEngageMode = 'mention' | 'pattern' | 'all';
-type ApiSenderScope = 'allowlist' | 'all';
-type ApiIgnoredMessagePolicy = 'drop' | 'silent';
-
-const ALL_PATTERN = '.';
-
-function dbToApiEngage(mode: DbEngageMode, pattern: string | null): ApiEngageMode {
-  if (mode === 'pattern') return pattern === ALL_PATTERN ? 'all' : 'pattern';
-  return 'mention';
-}
-function dbToApiSenderScope(s: DbSenderScope): ApiSenderScope {
-  return s === 'known' ? 'allowlist' : 'all';
-}
-function dbToApiIgnoredPolicy(p: DbIgnoredMessagePolicy): ApiIgnoredMessagePolicy {
-  return p === 'accumulate' ? 'silent' : 'drop';
-}
-
-interface WireRow extends MessagingGroupAgent {
-  mg_channel_type: string;
-  mg_platform_id: string;
-  mg_name: string | null;
-  ag_folder: string;
-  ag_name: string;
-}
-
-interface ChannelWireView {
-  id: string;
-  channelType: string;
-  messagingGroupId: string;
-  platformId: string;
-  displayName: string | null;
-  agentGroupId: string;
-  agentGroupFolder: string;
-  agentGroupName: string;
-  engageMode: ApiEngageMode;
-  engagePattern: string | null;
-  senderScope: ApiSenderScope;
-  ignoredMessagePolicy: ApiIgnoredMessagePolicy;
-  priority: number;
-  createdAt: string;
-}
-
-function rowToView(row: WireRow): ChannelWireView {
-  return {
-    id: row.id,
-    channelType: row.mg_channel_type,
-    messagingGroupId: row.messaging_group_id,
-    platformId: row.mg_platform_id,
-    displayName: row.mg_name,
-    agentGroupId: row.agent_group_id,
-    agentGroupFolder: row.ag_folder,
-    agentGroupName: row.ag_name,
-    engageMode: dbToApiEngage(row.engage_mode, row.engage_pattern),
-    engagePattern: row.engage_mode === 'pattern' && row.engage_pattern !== ALL_PATTERN ? row.engage_pattern : null,
-    senderScope: dbToApiSenderScope(row.sender_scope),
-    ignoredMessagePolicy: dbToApiIgnoredPolicy(row.ignored_message_policy),
-    priority: row.priority,
-    createdAt: row.created_at,
-  };
-}
-
 function listAllWires(): ChannelWireView[] {
   return (
     getDb()
-      .prepare<WireRow>(
+      .prepare<WireJoinRow>(
         `SELECT mga.*,
                 mg.channel_type AS mg_channel_type,
                 mg.platform_id  AS mg_platform_id,
@@ -100,7 +45,7 @@ function listAllWires(): ChannelWireView[] {
            JOIN agent_groups ag     ON ag.id = mga.agent_group_id
           ORDER BY mga.created_at DESC`,
       )
-      .all() as WireRow[]
+      .all() as WireJoinRow[]
   ).map(rowToView);
 }
 
@@ -159,7 +104,7 @@ export const channelTools: ToolDef[] = [
         id: { type: 'string' },
         engageMode: { type: 'string', enum: ['mention', 'pattern', 'all'] },
         engagePattern: { type: ['string', 'null'] },
-        senderScope: { type: 'string', enum: ['allowlist', 'all'] },
+        senderScope: { type: 'string', enum: ['allowlist', 'unrestricted'] },
         ignoredMessagePolicy: { type: 'string', enum: ['drop', 'silent'] },
         priority: { type: 'number' },
       },
@@ -170,26 +115,16 @@ export const channelTools: ToolDef[] = [
       const id = String(args.id ?? '');
       const current = getMessagingGroupAgent(id);
       if (!current) throw new Error(`channel wire not found: ${id}`);
-      const patch: Partial<MessagingGroupAgent> = {};
-      if (args.engageMode === 'all') {
-        patch.engage_mode = 'pattern';
-        patch.engage_pattern = ALL_PATTERN;
-      } else if (args.engageMode === 'pattern') {
-        patch.engage_mode = 'pattern';
-        if (typeof args.engagePattern === 'string' && args.engagePattern !== ALL_PATTERN) {
-          patch.engage_pattern = args.engagePattern;
-        }
-      } else if (args.engageMode === 'mention') {
-        patch.engage_mode = current.engage_mode === 'mention-sticky' ? 'mention-sticky' : 'mention';
-        patch.engage_pattern = null;
-      } else if (typeof args.engagePattern === 'string' || args.engagePattern === null) {
-        patch.engage_pattern = args.engagePattern as string | null;
-      }
-      if (args.senderScope === 'allowlist') patch.sender_scope = 'known';
-      else if (args.senderScope === 'all') patch.sender_scope = 'all';
-      if (args.ignoredMessagePolicy === 'silent') patch.ignored_message_policy = 'accumulate';
-      else if (args.ignoredMessagePolicy === 'drop') patch.ignored_message_policy = 'drop';
-      if (typeof args.priority === 'number' && Number.isFinite(args.priority)) patch.priority = args.priority;
+
+      // validatePatchInput inspects only the fields it knows; `id` and any
+      // future-compat keys are ignored. On `ok: false`, throw the reason —
+      // the HTTP route does the same translation on its end (400 + JSON
+      // error). Both surfaces now share the same rejection contract,
+      // including the engagePattern='.' sentinel guard.
+      const validated = validatePatchInput(args);
+      if (!validated.ok) throw new Error(validated.reason);
+
+      const patch = apiToDbPatch(validated.input, current);
       updateMessagingGroupAgent(id, patch);
       const after = getWireView(id);
       if (!after) throw new Error(`channel wire ${id} disappeared after update`);