@openparachute/agent 0.1.1 → 0.1.2

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to parachute-agent will be documented in this file.
 
+## [0.1.2] - 2026-05-05
+
+The first patch series after the 0.1.0 paraclaw → parachute-agent rename. Fourteen iterative cuts (rc.1 through rc.14) collapsed into one stable. No operator action required: every change is either a transparent fix, an additive UI affordance, or a behind-the-scenes test addition.
+
+### Fixed
+
+- **Master-key migration: detect the both-exist split-state explicitly.** `migrateMasterKeyLocation` previously silent-no-op'd when both `<PARACHUTE_DIR>/claw/master.key` and `<PARACHUTE_DIR>/agent/master.key` existed — masking the case where an earlier 0.1.x boot generated a fresh key at the new path before the legacy was copied (so encrypted secrets sealed under the legacy key became undecryptable). The function now logs a `warn` with both paths and copy-pasteable recovery commands. Standalone scripts (`init-cli-agent`, `init-first-agent`, `seed-discord`) that ran `migrateCentralDbLocation` now also run `migrateMasterKeyLocation` before opening the DB, so a script-driven first touch no longer skips the key copy. Also: SPA browser title `<title>Paraclaw</title>` → `<title>Parachute Agent</title>` and two stale GitHub repo links pointing at the renamed-from `paraclaw` URL — small follow-ups to the 0.1.0 brand sweep that landed in the same cut.
+
+- **Auto-retag the per-install container image when `INSTALL_SLUG` shifts (paraclaw#114).** `INSTALL_SLUG = sha1(process.cwd())[:8]`, so an operator dir-rename (the trigger that exposed this: `mv paraclaw parachute-agent`) flips the slug. Previously-built images carried the old slug; new container spawns went out under the new slug; `docker run` returned `code=125` ("image not found") and every Telegram message produced a silent crashloop. New `ensureContainerImage()` step at boot detects the mismatch and `docker tag`s any `parachute-agent-image-<peer-slug>:latest` it finds onto the expected name. Pre-0.1.0 `paraclaw-agent-<slug>:latest` peers also match (one cycle of compat). When no peer is on disk, the daemon now fails visibly at startup with an actionable error instead of crashlooping silently.
+
+- **Inbound: extract attachment files only after the row commits (paraclaw#96).** `writeSessionMessage` previously decoded base64 attachments and wrote files to `inbox/<messageId>/` *before* `INSERT … ON CONFLICT(id) DO NOTHING` returned. Once duplicate dispatch became a warm code path (sender-approval replay, Telegram getUpdates retry, chat-sdk re-emit), a replay carrying the same `messages_in.id` but mutated bytes silently clobbered the on-disk file under the original message id while the DB row stayed unchanged — divergent state with no audit trail. Reordered: insert with raw inline-base64 content, check `inserted`, and only when `inserted === true` extract files and `UPDATE messages_in SET content = ?` with the path-replaced form. Disk state now stays strictly downstream of the row commit.
+
+- **Wire-side `senderScope` vocabulary clash (paraclaw#94).** The wire vocab `'allowlist' | 'all'` shared the literal `'all'` with the DB-side `'all' | 'known'` — both meant "no sender filter", but the literal collision meant a grep-based rename of either side would silently break translation without a compile error. Renamed wire-side `'all'` → `'unrestricted'` so the two unions are now literal-disjoint; DB schema untouched (no migration). Touchpoints: HTTP + MCP translators, MCP `update-channel-wire` schema enum (now `['allowlist', 'unrestricted']`), `web/ui/src/lib/api.ts:SenderScope`, and the dropdown copy in `ChannelWireDetail.tsx`. Plus a defensive validation gate on the MCP handler — the SDK does not enforce `inputSchema` against `tools/call` arguments, so a stale-schema client sending the legacy `senderScope: 'all'` (or `ignoredMessagePolicy: 'accumulate'`, or a typo'd `engageMode`) would previously land past the rename gate, never match any branch, and silently no-op. Now explicitly rejected with a diagnostic error. **Breaking change to the API/MCP wire vocabulary** — pre-1.0, no operator-data risk.
+
+- **Mount-security imports `HOME_DIR` from `src/config.ts` (paraclaw#99).** `expandPath` in `src/modules/mount-security/index.ts` previously called `process.env.HOME || os.homedir()` directly — the only remaining offender after the rest of the host's HOME-derived paths routed through `config.ts`. Now imports the canonical `HOME_DIR`, so a future precedence-rule refactor (e.g. add a `PARACHUTE_AGENT_HOME` override) is one edit upstream. Default behavior unchanged. Mount-allowlist's on-disk location intentionally stays at `<HOME>/.config/parachute-agent/` (operator-host policy, not per-install runtime state) — pinned with a regression test.
+
+- **`putSecret` auto-seeds the owner assignment for scoped creates (paraclaw#127).** The default `agent_groups.secret_mode` is `selective` (migration 023). Before this fix, `putSecret(name, value, { agent_group_id })` inserted the `secrets` row without writing the matching `secret_assignments` row — leaving the row silently invisible to `resolveInjectableSecrets` (which gates on `secret_mode='all' OR assignment row exists`). The "+ New secret" → CredentialForm "free" mode in the SPA called only `putSecret` with no follow-up `setSecretAssignments`, so the standard create flow produced orphan rows whose values would never reach the agent container. Fix: `putSecret` writes the (id, owning_group) assignment row in the same transaction on INSERT (idempotent via `ON CONFLICT … DO NOTHING`); UPDATE/rotate leaves the assignment set alone (operator may have deliberately revoked an assignment, and a value rotation must not undo that).
+
+- **SPA OAuth bootstrap — three narrowing fixes (paraclaw#136, #137, #138).** (1) Drop `vault:read vault:write` from `REQUESTED_SCOPES` — the agent SPA is self-contained, every vault flow already runs the per-vault re-consent pattern (`vault:<name>:admin` via `extraScopes`), so the broad bootstrap scopes were dead weight on the consent screen ("this app wants to read/write all your vaults" — wrong story for an SPA whose vault touches are narrowly per-vault and on-demand). (2) Regression-pin OAuth `client_name` in the registerClient body — the hub renders this string verbatim on its DCR consent screen; the 0.1.0 brand sweep renamed it from `Paraclaw web UI` to `Parachute Agent web UI`, this pins the wire-level test. (3) Re-register OAuth client when `redirect_uri` changes — the hub binds each DCR `client_id` to the redirect_uri it registered with; if the SPA's mount path changes (operator flips `PARACHUTE_AGENT_WEB_MOUNT` from `/claw/` → `/agent/`, or any custom remount), the cached client_id stops matching and `/oauth/authorize` errors out before the consent screen. Extended `ClientRecord` to `{ client_id, redirect_uri }`, compare in `ensureClient`, treat mismatch (or legacy missing-field record) as cache miss → re-register. Legacy records self-heal on first 0.1.x reload.
+
+### Changed
+
+- **`services.json` self-registers `installDir` (paraclaw#115).** The agent's startup self-registration into `~/.parachute/services.json` now includes `installDir: process.cwd()` alongside the existing `name`/`port`/`paths`/`health`/`version` fields. Without it, hub's third-party-module lifecycle resolution (parachute-hub#84) couldn't locate the start command for `parachute restart agent` — the agent had a `.parachute/module.json` with `startCmd`, but hub needed `installDir` to know which checkout to drive.
+
+- **GroupDetail "Secrets" panel — what the agent will receive at next session spawn (paraclaw#104).** `/agent/groups/:folder` now surfaces a read-only Secrets section showing the same set `resolveInjectableSecrets()` would inject into a new container, with three scope badges that explain *why* each row is included: `scoped` (owned by this group), `assigned` (global with explicit assignment row), `global` (global reaching the group only because `secret_mode='all'`). On a name collision the scoped row wins and reports `scoped`, mirroring the host's resolution rule. Click-through routes to `/secrets?edit=<id>` with a deep-link param for SecretEditor. New `GET /api/groups/:folder/secrets` endpoint (scope `agent:read`) — metadata only, never decrypts. Empty state distinguishes between mode='selective' (reads as "by design") and mode='all' (suggests creating a secret).
+
+- **GroupDetail Secrets section — Retry button on error state (paraclaw#128).** Mirrors the existing AgentProviderSection pattern: the error banner now renders a Retry button bound to the same fetch callback so operators don't have to navigate away after a transient API failure.
+
+- **Channel-wire translator extracted into a single shared module (paraclaw#123).** `src/web/routes/channels.ts` and `src/mcp/tools/channels.ts` each maintained their own copy of the `Api*` types, the `VALID_API_*` enum arrays, the `dbToApi*` translator pair, and the `ChannelWireView` shape. That duplication was the structural drift hazard paraclaw#94 surfaced concretely. Lifted everything into `src/channels/api-translator.ts`; the HTTP route file now owns only the transport layer, the MCP file only the tool-def plumbing. A future enum change touches one file and both surfaces pick it up automatically. (Behavioral side note: the inline MCP handler used to silently *drop* `engagePattern='.'` because the DB sentinel for `engageMode='all'` would round-trip back as `'all'` on the next read; the shared validator now hard-rejects that input identically on both surfaces. Use `'\\.'` to match a literal dot.)
+
+- **Depersonalize test fixtures + comments.** Removed a real install-slug (`16f7e9e8`, the sha1 prefix of one operator's specific path) that had snuck into `src/container-runtime.test.ts` peer-image fixtures, plus a comment in `src/container-runtime.ts` that named the specific `mv` command from one operator's environment. Codebase should be operator-agnostic. Replaced with synthetic `cafef00d`. No behavior change.
+
+### Tests
+
+- **Integration coverage for `writeSessionMessage` dup-skip + sender-approval replay (paraclaw#97).** The unit test added with #95 proved `insertMessage` returns `inserted=false` on a duplicate id, but the write-path side effects layered above it were never asserted at the integration level. New `src/session-manager.dup-skip.test.ts` (4 tests using real session DBs and real fs: dup dispatch doesn't bump `sessions.last_active`, log payload shape, N-concurrent same-id absorption to one row + one inbox file, distinct ids in the same burst still land), plus 2 new tests in `src/modules/permissions/sender-approval.test.ts` exercising the approval-replay chain end-to-end (file at `inbox/<id>:<agentGroupId>/photo.jpg`, byte-preserved on `original_message` mutation under accumulate-mode wiring). Stash-and-rerun confirmed both regression tests catch the underlying #92/#95/#96 bugs.
+
+- **Parallel-equality lockstep guard for `resolveInjectableSecrets ↔ listInjectableSecretsForGroup` (paraclaw#129).** The two functions in `src/secrets/index.ts` are SQL-identical mirrors with a load-bearing doc-comment requiring lockstep edits — previously preserved only by careful reading and a #126-era reviewer note. Adds a `describe('… lockstep …')` block with an `expectLockstep` helper that calls both functions, asserts name-set equality, and walks each name through `getSecret` to verify the chosen row id (the `ORDER BY s.agent_group_id IS NULL` scoped-wins ordering) agrees with the plaintext returned. Five fixtures cover the rich-mix (scoped+all + global+assigned + global+mode=all + name collision), mode=selective, the orphaned-scoped corner, the unknown-agent-group selective-default path, and an empty store. Mechanical guard, no production code change.
+
+---
+
+For per-rc commit-level detail of the 0.1.2 patch series, see `git log v0.1.1..v0.1.2 -- src/ web/ui/src/` or the merged PRs (#113 through #139).
+
 ## [0.1.1] - 2026-05-05
 
 ### Changed

package/docs/design/2026-05-02-channel-policy-and-approval-routing.md

@@ -23,7 +23,7 @@ This doc proposes how to fix all three together. No impl until Aaron reads it.
 | `sender_scope` | `all` \| `known` | `all` = no-op; `known` = `canAccessAgentGroup(userId, agent_group_id)` must allow. Enforced via the `senderScopeGate` hook the permissions module registers. | `src/modules/permissions/index.ts:175-183` |
 | `ignored_message_policy` | `drop` \| `accumulate` | Branch on the *non-engaging* path: `drop` = silently skip; `accumulate` = still write the inbound row to the agent's session DB with `trigger=0`, so context is available next time it does engage | `src/router.ts:355-358` |
 
-Note the API surface (`src/web/routes/channels.ts:8-22`) uses different enum names that translate at the route boundary — `engageMode='all'` collapses to DB `engage_mode='pattern'` + `engage_pattern='.'`; `senderScope='allowlist'` ↔ `sender_scope='known'`; `ignoredMessagePolicy='silent'` ↔ `ignored_message_policy='accumulate'`. The UI sees the API names. The DB keeps the original ones. The translator is lossy on the `mention` ↔ `mention-sticky` distinction (renders both as `mention`); the `apiToDbPatch` at `src/web/routes/channels.ts:97-127` carefully preserves sticky on round-trip.
+Note the API surface (`src/web/routes/channels.ts:8-22`) uses different enum names that translate at the route boundary — `engageMode='all'` collapses to DB `engage_mode='pattern'` + `engage_pattern='.'`; `senderScope='allowlist'` ↔ `sender_scope='known'` and `senderScope='unrestricted'` ↔ `sender_scope='all'` (paraclaw#94 renamed wire-side `'all'` → `'unrestricted'` so the two `SenderScope` unions are literal-disjoint); `ignoredMessagePolicy='silent'` ↔ `ignored_message_policy='accumulate'`. The UI sees the API names. The DB keeps the original ones. The translator is lossy on the `mention` ↔ `mention-sticky` distinction (renders both as `mention`); the `apiToDbPatch` at `src/web/routes/channels.ts:97-127` carefully preserves sticky on round-trip.
 
 ### 1b. The MG-level knob
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Parachute Agent — per-session containerized AI agent companion.",
   "license": "AGPL-3.0",
   "type": "module",

package/scripts/init-cli-agent.ts

@@ -21,7 +21,7 @@ import path from 'path';
 
 import { CENTRAL_DB_PATH } from '../src/config.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
-import { initDb, migrateCentralDbLocation } from '../src/db/connection.js';
+import { initDb, migrateCentralDbLocation, migrateMasterKeyLocation } from '../src/db/connection.js';
 import {
   createMessagingGroup,
   createMessagingGroupAgent,
@@ -78,6 +78,7 @@ async function main(): Promise<void> {
   const args = parseArgs(process.argv.slice(2));
 
   migrateCentralDbLocation();
+  migrateMasterKeyLocation();
   const db = initDb(CENTRAL_DB_PATH);
   runMigrations(db);
 

package/scripts/init-first-agent.ts

@@ -35,7 +35,7 @@ import path from 'path';
 
 import { CENTRAL_DB_PATH, DATA_DIR } from '../src/config.js';
 import { createAgentGroup, getAgentGroupByFolder } from '../src/db/agent-groups.js';
-import { initDb, migrateCentralDbLocation } from '../src/db/connection.js';
+import { initDb, migrateCentralDbLocation, migrateMasterKeyLocation } from '../src/db/connection.js';
 import {
   createMessagingGroup,
   createMessagingGroupAgent,
@@ -170,6 +170,7 @@ async function main(): Promise<void> {
   const args = parseArgs(process.argv.slice(2));
 
   migrateCentralDbLocation();
+  migrateMasterKeyLocation();
   const db = initDb(CENTRAL_DB_PATH);
   runMigrations(db); // idempotent
 

package/scripts/seed-discord.ts

@@ -4,7 +4,7 @@
  * Usage: pnpm exec tsx scripts/seed-discord.ts
  */
 import { CENTRAL_DB_PATH } from '../src/config.js';
-import { initDb, migrateCentralDbLocation } from '../src/db/connection.js';
+import { initDb, migrateCentralDbLocation, migrateMasterKeyLocation } from '../src/db/connection.js';
 import { runMigrations } from '../src/db/migrations/index.js';
 import { createAgentGroup, getAgentGroup } from '../src/db/agent-groups.js';
 import {
@@ -14,6 +14,7 @@ import {
 } from '../src/db/messaging-groups.js';
 
 migrateCentralDbLocation();
+migrateMasterKeyLocation();
 const db = initDb(CENTRAL_DB_PATH);
 runMigrations(db);
 

package/src/channels/api-translator.test.ts

@@ -0,0 +1,306 @@
+/**
+ * Round-trip + validator coverage for the shared channel-wire translator
+ * (paraclaw#123). The HTTP and MCP surfaces both depend on this module to
+ * keep the wire ↔ DB enums in lockstep — paraclaw#94/#122 was the drift
+ * incident that motivated extracting these tests behind one file.
+ */
+import { describe, it, expect } from 'vitest';
+
+import type { MessagingGroupAgent } from '../types.js';
+import {
+  ALL_MESSAGES_PATTERN_SENTINEL,
+  apiToDbPatch,
+  dbToApiEngage,
+  dbToApiIgnoredPolicy,
+  dbToApiSenderScope,
+  rowToView,
+  validatePatchInput,
+  type WireJoinRow,
+} from './api-translator.js';
+
+function baseRow(overrides: Partial<WireJoinRow> = {}): WireJoinRow {
+  return {
+    id: 'mga-1',
+    messaging_group_id: 'mg-1',
+    agent_group_id: 'ag-1',
+    engage_mode: 'mention',
+    engage_pattern: null,
+    sender_scope: 'all',
+    ignored_message_policy: 'drop',
+    session_mode: 'shared',
+    priority: 0,
+    created_at: '2026-05-05T00:00:00Z',
+    mg_channel_type: 'discord',
+    mg_platform_id: 'guild-123',
+    mg_name: 'general',
+    ag_folder: 'research',
+    ag_name: 'Research',
+    ...overrides,
+  };
+}
+
+function baseCurrent(overrides: Partial<MessagingGroupAgent> = {}): MessagingGroupAgent {
+  return {
+    id: 'mga-1',
+    messaging_group_id: 'mg-1',
+    agent_group_id: 'ag-1',
+    engage_mode: 'mention',
+    engage_pattern: null,
+    sender_scope: 'all',
+    ignored_message_policy: 'drop',
+    session_mode: 'shared',
+    priority: 0,
+    created_at: '2026-05-05T00:00:00Z',
+    ...overrides,
+  };
+}
+
+describe('dbToApiEngage', () => {
+  it('mention + null → mention', () => {
+    expect(dbToApiEngage('mention', null)).toBe('mention');
+  });
+
+  it('mention-sticky collapses to mention on the wire', () => {
+    // The wire deliberately doesn't expose sticky — see api-translator.ts
+    // docblock. apiToDbPatch's mention-sticky preservation is what keeps
+    // sticky-mode rows from silently flattening on PATCHes that don't
+    // touch the engagement fields.
+    expect(dbToApiEngage('mention-sticky', null)).toBe('mention');
+  });
+
+  it("pattern + '.' sentinel → all", () => {
+    expect(dbToApiEngage('pattern', ALL_MESSAGES_PATTERN_SENTINEL)).toBe('all');
+  });
+
+  it('pattern + real regex body → pattern', () => {
+    expect(dbToApiEngage('pattern', '\\bdeploy\\b')).toBe('pattern');
+  });
+
+  it('pattern + null → pattern (defensive — schema disallows but translator must not crash)', () => {
+    expect(dbToApiEngage('pattern', null)).toBe('pattern');
+  });
+});
+
+describe('dbToApiSenderScope', () => {
+  it("DB 'known' → wire 'allowlist'", () => {
+    expect(dbToApiSenderScope('known')).toBe('allowlist');
+  });
+
+  it("DB 'all' → wire 'unrestricted' (paraclaw#94 — disjoint literals)", () => {
+    expect(dbToApiSenderScope('all')).toBe('unrestricted');
+  });
+});
+
+describe('dbToApiIgnoredPolicy', () => {
+  it("DB 'accumulate' → wire 'silent'", () => {
+    expect(dbToApiIgnoredPolicy('accumulate')).toBe('silent');
+  });
+
+  it("DB 'drop' → wire 'drop'", () => {
+    expect(dbToApiIgnoredPolicy('drop')).toBe('drop');
+  });
+});
+
+describe('rowToView', () => {
+  it('projects every join column onto the wire view', () => {
+    const view = rowToView(
+      baseRow({
+        engage_mode: 'pattern',
+        engage_pattern: '\\bping\\b',
+        sender_scope: 'known',
+        ignored_message_policy: 'accumulate',
+        priority: 5,
+      }),
+    );
+    expect(view).toEqual({
+      id: 'mga-1',
+      channelType: 'discord',
+      messagingGroupId: 'mg-1',
+      platformId: 'guild-123',
+      displayName: 'general',
+      agentGroupId: 'ag-1',
+      agentGroupFolder: 'research',
+      agentGroupName: 'Research',
+      engageMode: 'pattern',
+      engagePattern: '\\bping\\b',
+      senderScope: 'allowlist',
+      ignoredMessagePolicy: 'silent',
+      priority: 5,
+      createdAt: '2026-05-05T00:00:00Z',
+    });
+  });
+
+  it("collapses pattern + '.' to engageMode='all' and nulls engagePattern on the wire", () => {
+    const view = rowToView(baseRow({ engage_mode: 'pattern', engage_pattern: ALL_MESSAGES_PATTERN_SENTINEL }));
+    expect(view.engageMode).toBe('all');
+    expect(view.engagePattern).toBeNull();
+  });
+
+  it('mention mode never leaks the engage_pattern column to the wire', () => {
+    // In practice the schema keeps engage_pattern null for mention rows, but
+    // the projection must not surface stale pattern bodies if a row drifts.
+    const view = rowToView(baseRow({ engage_mode: 'mention', engage_pattern: 'leftover' }));
+    expect(view.engageMode).toBe('mention');
+    expect(view.engagePattern).toBeNull();
+  });
+});
+
+describe('apiToDbPatch — engageMode encoding', () => {
+  it("engageMode='all' → mode=pattern + pattern='.'", () => {
+    const out = apiToDbPatch({ engageMode: 'all' }, baseCurrent());
+    expect(out.engage_mode).toBe('pattern');
+    expect(out.engage_pattern).toBe(ALL_MESSAGES_PATTERN_SENTINEL);
+  });
+
+  it('engageMode=pattern + engagePattern → both written', () => {
+    const out = apiToDbPatch({ engageMode: 'pattern', engagePattern: '\\bdeploy\\b' }, baseCurrent());
+    expect(out.engage_mode).toBe('pattern');
+    expect(out.engage_pattern).toBe('\\bdeploy\\b');
+  });
+
+  it('engageMode=pattern without engagePattern → only mode set, pattern preserved on the row', () => {
+    // The PATCH-shape semantic: an undefined field means "leave it alone."
+    // The DB-side row already has the prior pattern; we don't overwrite it.
+    const out = apiToDbPatch({ engageMode: 'pattern' }, baseCurrent({ engage_pattern: 'old' }));
+    expect(out.engage_mode).toBe('pattern');
+    expect(out).not.toHaveProperty('engage_pattern');
+  });
+
+  it("engageMode='mention' nulls engage_pattern", () => {
+    const out = apiToDbPatch({ engageMode: 'mention' }, baseCurrent());
+    expect(out.engage_mode).toBe('mention');
+    expect(out.engage_pattern).toBeNull();
+  });
+
+  it("engageMode='mention' preserves mention-sticky when current row is sticky", () => {
+    // Wire doesn't expose sticky → both mention + mention-sticky show as
+    // 'mention' on the read side. A PATCH that flips back to 'mention' on
+    // the wire shouldn't silently demote the sticky bit on the row.
+    const out = apiToDbPatch({ engageMode: 'mention' }, baseCurrent({ engage_mode: 'mention-sticky' }));
+    expect(out.engage_mode).toBe('mention-sticky');
+    expect(out.engage_pattern).toBeNull();
+  });
+
+  it('engagePattern alone (no engageMode) → only pattern body changes', () => {
+    const out = apiToDbPatch({ engagePattern: '\\bnew\\b' }, baseCurrent({ engage_mode: 'pattern' }));
+    expect(out).not.toHaveProperty('engage_mode');
+    expect(out.engage_pattern).toBe('\\bnew\\b');
+  });
+});
+
+describe('apiToDbPatch — sender scope and ignored policy', () => {
+  it("senderScope 'allowlist' → DB 'known'", () => {
+    expect(apiToDbPatch({ senderScope: 'allowlist' }, baseCurrent()).sender_scope).toBe('known');
+  });
+
+  it("senderScope 'unrestricted' → DB 'all'", () => {
+    expect(apiToDbPatch({ senderScope: 'unrestricted' }, baseCurrent()).sender_scope).toBe('all');
+  });
+
+  it("ignoredMessagePolicy 'silent' → DB 'accumulate'", () => {
+    expect(apiToDbPatch({ ignoredMessagePolicy: 'silent' }, baseCurrent()).ignored_message_policy).toBe('accumulate');
+  });
+
+  it("ignoredMessagePolicy 'drop' → DB 'drop'", () => {
+    expect(apiToDbPatch({ ignoredMessagePolicy: 'drop' }, baseCurrent()).ignored_message_policy).toBe('drop');
+  });
+
+  it('priority passes through unchanged', () => {
+    expect(apiToDbPatch({ priority: 7 }, baseCurrent()).priority).toBe(7);
+  });
+
+  it('empty input → empty patch', () => {
+    expect(apiToDbPatch({}, baseCurrent())).toEqual({});
+  });
+});
+
+describe('validatePatchInput', () => {
+  it('rejects non-object body', () => {
+    expect(validatePatchInput(null)).toEqual({ ok: false, reason: 'body must be an object' });
+    expect(validatePatchInput('string')).toEqual({ ok: false, reason: 'body must be an object' });
+    expect(validatePatchInput(42)).toEqual({ ok: false, reason: 'body must be an object' });
+  });
+
+  it('passes a fully-populated valid body', () => {
+    const result = validatePatchInput({
+      engageMode: 'pattern',
+      engagePattern: '\\bping\\b',
+      senderScope: 'allowlist',
+      ignoredMessagePolicy: 'silent',
+      priority: 3,
+    });
+    expect(result).toEqual({
+      ok: true,
+      input: {
+        engageMode: 'pattern',
+        engagePattern: '\\bping\\b',
+        senderScope: 'allowlist',
+        ignoredMessagePolicy: 'silent',
+        priority: 3,
+      },
+    });
+  });
+
+  it("rejects legacy wire-side senderScope='all' (paraclaw#94 rename)", () => {
+    // Pre-paraclaw#94 the wire used 'all' on both axes; the rename to
+    // 'unrestricted' was specifically to make a grep-refactor unable to
+    // conflate the wire and DB unions. The validator must now reject the
+    // old literal.
+    const result = validatePatchInput({ senderScope: 'all' });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toContain('senderScope');
+  });
+
+  it("rejects legacy ignoredMessagePolicy='accumulate' on the wire", () => {
+    // 'accumulate' is the DB-side spelling. The wire spelling is 'silent'.
+    const result = validatePatchInput({ ignoredMessagePolicy: 'accumulate' });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toContain('ignoredMessagePolicy');
+  });
+
+  it("rejects engageMode='mention-sticky' (DB-only literal)", () => {
+    const result = validatePatchInput({ engageMode: 'mention-sticky' });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toContain('engageMode');
+  });
+
+  it("rejects bare '.' as engagePattern (sentinel reservation)", () => {
+    // Storing '.' would silently round-trip back as engageMode='all' on the
+    // next read. The fix landed in paraclaw#122 — keep the regression here.
+    const result = validatePatchInput({ engagePattern: ALL_MESSAGES_PATTERN_SENTINEL });
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.reason).toMatch(/sentinel/);
+  });
+
+  it("accepts escaped literal-dot pattern '\\\\.'", () => {
+    // The error message above tells the caller to escape; that escaped
+    // form must round-trip cleanly.
+    const result = validatePatchInput({ engagePattern: '\\.' });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.input.engagePattern).toBe('\\.');
+  });
+
+  it('accepts engagePattern=null (clear-the-pattern PATCH)', () => {
+    const result = validatePatchInput({ engagePattern: null });
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(result.input.engagePattern).toBeNull();
+  });
+
+  it('rejects non-string non-null engagePattern', () => {
+    expect(validatePatchInput({ engagePattern: 5 }).ok).toBe(false);
+    expect(validatePatchInput({ engagePattern: {} }).ok).toBe(false);
+  });
+
+  it('rejects non-finite priority', () => {
+    expect(validatePatchInput({ priority: Infinity }).ok).toBe(false);
+    expect(validatePatchInput({ priority: NaN }).ok).toBe(false);
+    expect(validatePatchInput({ priority: '5' }).ok).toBe(false);
+  });
+
+  it('drops unknown keys silently (forward-compat)', () => {
+    // The validator only inspects fields it knows; unknown keys aren't an
+    // error, they just don't make it into the typed output.
+    const result = validatePatchInput({ engageMode: 'mention', futureField: 'nope' });
+    expect(result).toEqual({ ok: true, input: { engageMode: 'mention' } });
+  });
+});

package/src/channels/api-translator.ts

@@ -0,0 +1,214 @@
+/**
+ * Shared translator between the storage shape (`messaging_group_agents` row,
+ * snake_case + legacy enum names) and the API contract that both `/api/channels`
+ * and the MCP `*-channel-wire` tools speak.
+ *
+ * Background. Both surfaces used to maintain their own copy of these types,
+ * constants, translators, and the patch validator. The duplication was a
+ * structural drift hazard: paraclaw#94 / PR #122 surfaced exactly that class
+ * — the rename of wire-side `'all'` → `'unrestricted'` initially landed only
+ * the HTTP-side validator and missed the MCP-side silent-no-op. Extracting
+ * here makes the drift class structurally impossible: a future enum change
+ * touches one file, both surfaces pick it up. paraclaw#123.
+ *
+ * API contract: engageMode = mention | pattern | all, senderScope = allowlist
+ * | unrestricted, ignoredMessagePolicy = drop | silent.
+ *
+ * DB shape (still pre-rebuild): engage_mode = mention | pattern |
+ * mention-sticky (with engage_pattern='.' as the "match every message"
+ * sentinel), sender_scope = all | known, ignored_message_policy = drop |
+ * accumulate. The translator collapses pattern + '.' into the API's `all`,
+ * lossy on mention-sticky (rendered as `mention` to the wire).
+ *
+ * The validator returns a discriminated result rather than throwing so each
+ * caller can pick its own error idiom: HTTP wraps `{ ok: false }` into a
+ * 400 + JSON error; MCP throws on `{ ok: false }`.
+ */
+import type {
+  EngageMode as DbEngageMode,
+  IgnoredMessagePolicy as DbIgnoredMessagePolicy,
+  MessagingGroupAgent,
+  SenderScope as DbSenderScope,
+} from '../types.js';
+
+export type ApiEngageMode = 'mention' | 'pattern' | 'all';
+export type ApiSenderScope = 'allowlist' | 'unrestricted';
+export type ApiIgnoredMessagePolicy = 'drop' | 'silent';
+
+export const ALL_MESSAGES_PATTERN_SENTINEL = '.';
+
+export const VALID_API_ENGAGE_MODES: ApiEngageMode[] = ['mention', 'pattern', 'all'];
+export const VALID_API_SENDER_SCOPES: ApiSenderScope[] = ['allowlist', 'unrestricted'];
+export const VALID_API_IGNORED_POLICIES: ApiIgnoredMessagePolicy[] = ['drop', 'silent'];
+
+export 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;
+}
+
+export interface WireJoinRow extends MessagingGroupAgent {
+  mg_channel_type: string;
+  mg_platform_id: string;
+  mg_name: string | null;
+  ag_folder: string;
+  ag_name: string;
+}
+
+export interface PatchInput {
+  engageMode?: ApiEngageMode;
+  engagePattern?: string | null;
+  senderScope?: ApiSenderScope;
+  ignoredMessagePolicy?: ApiIgnoredMessagePolicy;
+  priority?: number;
+}
+
+export interface DbPatch {
+  engage_mode?: DbEngageMode;
+  engage_pattern?: string | null;
+  sender_scope?: DbSenderScope;
+  ignored_message_policy?: DbIgnoredMessagePolicy;
+  priority?: number;
+}
+
+export function dbToApiEngage(mode: DbEngageMode, pattern: string | null): ApiEngageMode {
+  if (mode === 'pattern') {
+    return pattern === ALL_MESSAGES_PATTERN_SENTINEL ? 'all' : 'pattern';
+  }
+  // mention + mention-sticky both render as 'mention' on the wire today.
+  return 'mention';
+}
+
+export function dbToApiSenderScope(s: DbSenderScope): ApiSenderScope {
+  return s === 'known' ? 'allowlist' : 'unrestricted';
+}
+
+export function dbToApiIgnoredPolicy(p: DbIgnoredMessagePolicy): ApiIgnoredMessagePolicy {
+  return p === 'accumulate' ? 'silent' : 'drop';
+}
+
+export function rowToView(row: WireJoinRow): 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_MESSAGES_PATTERN_SENTINEL ? row.engage_pattern : null,
+    senderScope: dbToApiSenderScope(row.sender_scope),
+    ignoredMessagePolicy: dbToApiIgnoredPolicy(row.ignored_message_policy),
+    priority: row.priority,
+    createdAt: row.created_at,
+  };
+}
+
+export function apiToDbPatch(input: PatchInput, current: MessagingGroupAgent): DbPatch {
+  const out: DbPatch = {};
+
+  // engageMode is paired with engagePattern: 'all' encodes as
+  // mode='pattern' + pattern='.', which the router treats as match-every.
+  if (input.engageMode !== undefined) {
+    if (input.engageMode === 'all') {
+      out.engage_mode = 'pattern';
+      out.engage_pattern = ALL_MESSAGES_PATTERN_SENTINEL;
+    } else if (input.engageMode === 'pattern') {
+      out.engage_mode = 'pattern';
+      // Pattern body comes from input.engagePattern when present; otherwise
+      // preserve what's already on the row. validatePatchInput already
+      // rejects bare '.' here so the next read can't silently collapse to
+      // 'all'.
+      if (input.engagePattern !== undefined) {
+        out.engage_pattern = input.engagePattern;
+      }
+    } else if (input.engageMode === 'mention') {
+      // Preserve mention-sticky if that's what's currently on the row;
+      // collapsing it to plain mention here would silently change router
+      // behavior (sticky engagement persists across replies). The wire
+      // doesn't expose sticky → it sees `mention` for both, but a PATCH
+      // that doesn't touch the sticky distinction shouldn't lose it.
+      out.engage_mode = current.engage_mode === 'mention-sticky' ? 'mention-sticky' : 'mention';
+      out.engage_pattern = null;
+    }
+  } else if (input.engagePattern !== undefined) {
+    // pattern body changed without changing the mode.
+    out.engage_pattern = input.engagePattern;
+  }
+
+  if (input.senderScope !== undefined) {
+    // wire 'unrestricted' → DB 'all'. validatePatchInput has already gated
+    // the union to the two known values, so the binary mapping is safe.
+    out.sender_scope = input.senderScope === 'allowlist' ? 'known' : 'all';
+  }
+  if (input.ignoredMessagePolicy !== undefined) {
+    out.ignored_message_policy = input.ignoredMessagePolicy === 'silent' ? 'accumulate' : 'drop';
+  }
+  if (input.priority !== undefined) {
+    out.priority = input.priority;
+  }
+  return out;
+}
+
+export type ValidatePatchResult = { ok: true; input: PatchInput } | { ok: false; reason: string };
+
+export function validatePatchInput(body: unknown): ValidatePatchResult {
+  if (!body || typeof body !== 'object') return { ok: false, reason: 'body must be an object' };
+  const b = body as Record<string, unknown>;
+  const out: PatchInput = {};
+  if ('engageMode' in b) {
+    if (!VALID_API_ENGAGE_MODES.includes(b.engageMode as ApiEngageMode)) {
+      return { ok: false, reason: `invalid engageMode: ${String(b.engageMode)}` };
+    }
+    out.engageMode = b.engageMode as ApiEngageMode;
+  }
+  if ('engagePattern' in b) {
+    if (b.engagePattern !== null && typeof b.engagePattern !== 'string') {
+      return { ok: false, reason: 'engagePattern must be string or null' };
+    }
+    // Bare '.' is the wire-format sentinel for engageMode='all' — accepting
+    // it as a literal pattern would silently round-trip back as 'all' on the
+    // next read and lose the user's intent. Force the caller to disambiguate.
+    if (b.engagePattern === ALL_MESSAGES_PATTERN_SENTINEL) {
+      return {
+        ok: false,
+        reason:
+          "engagePattern '.' is reserved as the 'all' sentinel — use '\\\\.' (escaped) to match a literal dot, or set engageMode to 'all'",
+      };
+    }
+    out.engagePattern = b.engagePattern as string | null;
+  }
+  if ('senderScope' in b) {
+    if (!VALID_API_SENDER_SCOPES.includes(b.senderScope as ApiSenderScope)) {
+      return { ok: false, reason: `invalid senderScope: ${String(b.senderScope)}` };
+    }
+    out.senderScope = b.senderScope as ApiSenderScope;
+  }
+  if ('ignoredMessagePolicy' in b) {
+    if (!VALID_API_IGNORED_POLICIES.includes(b.ignoredMessagePolicy as ApiIgnoredMessagePolicy)) {
+      return { ok: false, reason: `invalid ignoredMessagePolicy: ${String(b.ignoredMessagePolicy)}` };
+    }
+    out.ignoredMessagePolicy = b.ignoredMessagePolicy as ApiIgnoredMessagePolicy;
+  }
+  if ('priority' in b) {
+    if (typeof b.priority !== 'number' || !Number.isFinite(b.priority)) {
+      return { ok: false, reason: 'priority must be a finite number' };
+    }
+    out.priority = b.priority;
+  }
+  return { ok: true, input: out };
+}