@openparachute/agent 0.1.0 → 0.1.2

package/LICENSE-NANOCLAW-MIT

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -187,4 +187,11 @@ See [CHANGELOG.md](CHANGELOG.md) for breaking changes.
 
 ## License
 
-MIT
+parachute-agent is licensed under the GNU Affero General Public License v3.0
+([LICENSE](./LICENSE)).
+
+It is a derivative of [NanoClaw](https://github.com/qwibitai/nanoclaw) (MIT —
+see [LICENSE-NANOCLAW-MIT](./LICENSE-NANOCLAW-MIT) for the original copyright
+notice). Substantial modifications and the combined work are AGPL-3.0; the
+original NanoClaw code remains MIT-licensed and can be obtained from the
+upstream project.

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,7 +1,8 @@
 {
   "name": "@openparachute/agent",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Parachute Agent — per-session containerized AI agent companion.",
+  "license": "AGPL-3.0",
   "type": "module",
   "packageManager": "pnpm@10.33.0",
   "main": "src/index.ts",

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

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');