@openparachute/agent 0.1.2 → 0.2.0

package/src/channels/telegram.ts

@@ -1,279 +0,0 @@
-/**
- * Telegram channel adapter (v2) — uses Chat SDK bridge, with a pairing
- * interceptor wrapped around onInbound to verify chat ownership before
- * registration. See telegram-pairing.ts for the why.
- */
-import { createTelegramAdapter } from '@chat-adapter/telegram';
-
-import { readEnvFile } from '../env.js';
-import { log } from '../log.js';
-import { createMessagingGroup, getMessagingGroupByPlatform, updateMessagingGroup } from '../db/messaging-groups.js';
-import { grantRole, hasAnyOwner } from '../modules/permissions/db/user-roles.js';
-import { upsertUser } from '../modules/permissions/db/users.js';
-import { createChatSdkBridge, type ReplyContext } from './chat-sdk-bridge.js';
-import { sanitizeTelegramLegacyMarkdown } from './telegram-markdown-sanitize.js';
-import { registerChannelAdapter } from './channel-registry.js';
-import type { ChannelAdapter, ChannelSetup, InboundMessage } from './adapter.js';
-import { tryConsume } from './telegram-pairing.js';
-
-/**
- * Retry a one-shot operation that can fail on transient network errors at
- * cold-start (DNS hiccups, brief upstream outages). Exponential backoff capped
- * at 5 attempts — if the network is truly down we surface it instead of
- * hanging the service indefinitely.
- */
-async function withRetry<T>(fn: () => Promise<T>, label: string, maxAttempts = 5): Promise<T> {
-  let lastErr: unknown;
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await fn();
-    } catch (err) {
-      lastErr = err;
-      if (attempt === maxAttempts) break;
-      const delay = Math.min(16000, 1000 * 2 ** (attempt - 1));
-      log.warn('Telegram setup failed, retrying', { label, attempt, delayMs: delay, err });
-      await new Promise((r) => setTimeout(r, delay));
-    }
-  }
-  throw lastErr;
-}
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function extractReplyContext(raw: Record<string, any>): ReplyContext | null {
-  if (!raw.reply_to_message) return null;
-  const reply = raw.reply_to_message;
-  return {
-    text: reply.text || reply.caption || '',
-    sender: reply.from?.first_name || reply.from?.username || 'Unknown',
-  };
-}
-
-interface BotIdentity {
-  botId: string;
-  username: string | null;
-}
-
-/**
- * Look up the bot's id and username via Telegram `getMe`. Required up-front so
- * the bridge can encode v2 platform_ids (`<channel>:<botId>:<native>`) before
- * any inbound traffic arrives. Throws on failure — paraclaw can't operate a
- * Telegram channel adapter without a bot identity for keying.
- */
-async function fetchBotIdentity(token: string): Promise<BotIdentity> {
-  const res = await fetch(`https://api.telegram.org/bot${token}/getMe`);
-  const json = (await res.json()) as {
-    ok: boolean;
-    result?: { id?: number; username?: string };
-    description?: string;
-  };
-  if (!json.ok || !json.result?.id) {
-    throw new Error(`Telegram getMe failed: ${json.description ?? 'no result'}`);
-  }
-  return { botId: String(json.result.id), username: json.result.username ?? null };
-}
-
-function isGroupPlatformId(platformId: string): boolean {
-  // platformId is v2 (`telegram:<botId>:<chatId>`); the chat id is the third
-  // segment. Negative chat IDs are groups/channels.
-  const parts = platformId.split(':');
-  const id = parts.length >= 3 ? parts[2] : (parts.pop() ?? '');
-  return id.startsWith('-');
-}
-
-interface InboundFields {
-  text: string;
-  authorUserId: string | null;
-}
-
-function readInboundFields(message: InboundMessage): InboundFields {
-  if (message.kind !== 'chat-sdk' || !message.content || typeof message.content !== 'object') {
-    return { text: '', authorUserId: null };
-  }
-  const c = message.content as { text?: string; author?: { userId?: string } };
-  return { text: c.text ?? '', authorUserId: c.author?.userId ?? null };
-}
-
-/**
- * Build an onInbound interceptor that consumes pairing codes before they
- * reach the router. On match: records the chat + its paired user, promotes
- * the user to owner if the instance has no owner yet, and short-circuits.
- * On miss: forwards to the host.
- */
-/**
- * Send a one-shot confirmation back to the paired chat. Best-effort — failures
- * are logged but never propagated, so a Telegram outage can't undo a successful
- * pairing or trigger the interceptor's fail-open path.
- */
-async function sendPairingConfirmation(token: string, platformId: string): Promise<void> {
-  // platformId is v2 (`telegram:<botId>:<chatId>`); the chat id is everything
-  // after the second colon. Slice past those two segments before posting.
-  const parts = platformId.split(':');
-  const chatId = parts.length >= 3 ? parts.slice(2).join(':') : parts.slice(1).join(':');
-  if (!chatId) return;
-  try {
-    const res = await fetch(`https://api.telegram.org/bot${token}/sendMessage`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({
-        chat_id: chatId,
-        text: "Pairing success! I'm spinning up the agent now, you'll get a message from them shortly.",
-      }),
-    });
-    if (!res.ok) {
-      log.warn('Telegram pairing confirmation non-OK', { status: res.status });
-    }
-  } catch (err) {
-    log.warn('Telegram pairing confirmation failed', { err });
-  }
-}
-
-function createPairingInterceptor(
-  botUsername: string | null,
-  hostOnInbound: ChannelSetup['onInbound'],
-  token: string,
-): ChannelSetup['onInbound'] {
-  return async (platformId, threadId, message) => {
-    try {
-      if (!botUsername) {
-        hostOnInbound(platformId, threadId, message);
-        return;
-      }
-      const { text, authorUserId } = readInboundFields(message);
-      if (!text) {
-        hostOnInbound(platformId, threadId, message);
-        return;
-      }
-      const consumed = await tryConsume({
-        text,
-        botUsername,
-        platformId,
-        isGroup: isGroupPlatformId(platformId),
-        adminUserId: authorUserId,
-      });
-      if (!consumed) {
-        hostOnInbound(platformId, threadId, message);
-        return;
-      }
-      // Pairing matched — record the chat and short-circuit so the
-      // code-bearing message never reaches an agent. Privilege is now a
-      // property of the paired user, not the chat: upsert the user, and if
-      // this instance has no owner yet, promote them to owner.
-      const existing = getMessagingGroupByPlatform('telegram', platformId);
-      if (existing) {
-        updateMessagingGroup(existing.id, {
-          is_group: consumed.consumed!.isGroup ? 1 : 0,
-        });
-      } else {
-        createMessagingGroup({
-          id: `mg-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
-          channel_type: 'telegram',
-          platform_id: platformId,
-          name: consumed.consumed!.name,
-          is_group: consumed.consumed!.isGroup ? 1 : 0,
-          unknown_sender_policy: 'strict',
-          created_at: new Date().toISOString(),
-        });
-      }
-
-      const pairedUserId = `telegram:${consumed.consumed!.adminUserId}`;
-      upsertUser({
-        id: pairedUserId,
-        kind: 'telegram',
-        display_name: null,
-        created_at: new Date().toISOString(),
-      });
-
-      let promotedToOwner = false;
-      if (!hasAnyOwner()) {
-        grantRole({
-          user_id: pairedUserId,
-          role: 'owner',
-          agent_group_id: null,
-          granted_by: null,
-          granted_at: new Date().toISOString(),
-        });
-        promotedToOwner = true;
-      }
-
-      log.info('Telegram pairing accepted — chat registered', {
-        platformId,
-        pairedUser: pairedUserId,
-        promotedToOwner,
-        intent: consumed.intent,
-      });
-
-      await sendPairingConfirmation(token, platformId);
-    } catch (err) {
-      log.error('Telegram pairing interceptor error', { err });
-      // Fail open: pass through so a pairing bug doesn't break normal traffic.
-      hostOnInbound(platformId, threadId, message);
-    }
-  };
-}
-
-/**
- * Build (but don't `setup()`) a Telegram channel adapter for the given bot
- * token. Resolves bot identity eagerly via `getMe` so the bridge can encode
- * v2 platform_ids before any inbound traffic arrives.
- *
- * Used by:
- *   - the channel-registry's startup factory below (single bot via `.env`)
- *   - `registerBotAdapter('telegram', { token })` (dynamic per-bot adds via
- *     `POST /api/channels/telegram/register-bot`, see channel-registry.ts)
- *   - the secrets-backed startup scan (one adapter per
- *     `CHANNEL_BOT_TOKEN:telegram:*` row across restarts)
- *
- * Throws on getMe failure; callers decide whether the bot is essential
- * (factory: log + skip) or operator-driven (register-bot: surface as 4xx).
- */
-export async function spawnTelegramAdapter(token: string): Promise<ChannelAdapter> {
-  const identity = await withRetry(() => fetchBotIdentity(token), 'getMe');
-  const { botId, username } = identity;
-
-  const telegramAdapter = createTelegramAdapter({
-    botToken: token,
-    mode: 'polling',
-  });
-  const bridge = createChatSdkBridge({
-    adapter: telegramAdapter,
-    botId,
-    concurrency: 'concurrent',
-    extractReplyContext,
-    supportsThreads: false,
-    transformOutboundText: sanitizeTelegramLegacyMarkdown,
-  });
-
-  return {
-    ...bridge,
-    botId,
-    async setup(hostConfig: ChannelSetup) {
-      const intercepted: ChannelSetup = {
-        ...hostConfig,
-        onInbound: createPairingInterceptor(username, hostConfig.onInbound, token),
-      };
-      return withRetry(() => bridge.setup(intercepted), 'bridge.setup');
-    },
-  };
-}
-
-registerChannelAdapter('telegram', {
-  factory: async () => {
-    const env = readEnvFile(['TELEGRAM_BOT_TOKEN']);
-    if (!env.TELEGRAM_BOT_TOKEN) return null;
-    return spawnTelegramAdapter(env.TELEGRAM_BOT_TOKEN);
-  },
-  /**
-   * The token is the only thing Telegram needs — the bot's id and username
-   * are recovered via getMe inside spawnTelegramAdapter. The secretName's
-   * trailing segment IS the botId, but we don't need to parse it; the adapter
-   * resolves identity itself.
-   */
-  spawnFromSecret: async (_secretName, secretValue) => {
-    try {
-      return await spawnTelegramAdapter(secretValue);
-    } catch (err) {
-      log.error('Telegram spawnFromSecret failed', { err });
-      return null;
-    }
-  },
-});

package/src/channels/trust-hint.test.ts

@@ -1,48 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { recordTrustHint, consumeTrustHint, _resetTrustHintsForTest } from './trust-hint.js';
-
-describe('channel trust hint', () => {
-  beforeEach(() => {
-    _resetTrustHintsForTest();
-    vi.useFakeTimers();
-  });
-  afterEach(() => {
-    vi.useRealTimers();
-    _resetTrustHintsForTest();
-  });
-
-  it('returns true once for a recorded triple, then false on second consume', () => {
-    recordTrustHint('telegram', 'bot-1', 'op-42');
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(true);
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(false);
-  });
-
-  it('returns false for a triple that was never recorded', () => {
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(false);
-  });
-
-  it('discriminates by all three key parts', () => {
-    recordTrustHint('telegram', 'bot-1', 'op-42');
-    expect(consumeTrustHint('discord', 'bot-1', 'op-42')).toBe(false);
-    expect(consumeTrustHint('telegram', 'bot-2', 'op-42')).toBe(false);
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-43')).toBe(false);
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(true);
-  });
-
-  it('expires hints after the TTL', () => {
-    recordTrustHint('telegram', 'bot-1', 'op-42');
-    vi.advanceTimersByTime(5 * 60 * 1000 + 1);
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(false);
-  });
-
-  it('keeps hints valid up to the TTL boundary', () => {
-    recordTrustHint('telegram', 'bot-1', 'op-42');
-    vi.advanceTimersByTime(5 * 60 * 1000 - 1);
-    expect(consumeTrustHint('telegram', 'bot-1', 'op-42')).toBe(true);
-  });
-
-  it('treats empty operatorUserId as a no-op (Discord wires)', () => {
-    recordTrustHint('discord', 'bot-app-id', '');
-    expect(consumeTrustHint('discord', 'bot-app-id', '')).toBe(false);
-  });
-});

package/src/channels/trust-hint.ts

@@ -1,75 +0,0 @@
-/**
- * Operator-self-wire trust hint (paraclaw#67 — Proposal B).
- *
- * When the operator submits `/agent/channels/new`, we record an in-memory
- * hint keyed `(channelType, botId, operatorUserId)` saying "the operator
- * just wired this bot themselves; the next inbound from them on this bot
- * should bypass the unwired-channel approval gate and route as trusted."
- *
- * Why in-memory (no table): hints are 5-minute things. If paraclaw
- * restarts in that window, the operator who hasn't DM'd the bot yet
- * starts from a wired MGA anyway (Proposal A makes wire the spawn point);
- * no hint needed on the cold path. A persistent table would only matter
- * if we wanted hints to survive crashes mid-window — that's not worth
- * the migration cost or sweep complexity.
- *
- * Why bound to operatorUserId, not just (channel, bot): the form captures
- * the operator's user id explicitly (Telegram operatorUserId field).
- * Trusting only that user means a third-party who DMs the bot in the
- * trust window still goes through the approval flow — exactly the
- * cautious behavior we want.
- *
- * Discord: the form doesn't capture an operator user id (sender_scope
- * 'all' on the wire MGA already covers that case at the routing layer),
- * so Discord wires record no hint and the router check is a no-op for
- * Discord inbounds.
- */
-const TTL_MS = 5 * 60 * 1000;
-
-type HintKey = string;
-
-function key(channelType: string, botId: string, operatorUserId: string): HintKey {
-  return `${channelType}\0${botId}\0${operatorUserId}`;
-}
-
-const hints = new Map<HintKey, number>();
-
-function sweep(now: number): void {
-  // O(n) sweep over active hints; n stays tiny in practice (operator-window bounded).
-  for (const [k, expiresAt] of hints) {
-    if (expiresAt <= now) hints.delete(k);
-  }
-}
-
-/**
- * Record that the operator just wired `botId` on `channelType` and
- * identifies as `operatorUserId`. The next inbound matching this triple
- * within {@link TTL_MS} bypasses the unwired-channel approval gate.
- *
- * No-op if `operatorUserId` is empty (Discord wires don't capture one).
- */
-export function recordTrustHint(channelType: string, botId: string, operatorUserId: string): void {
-  if (!operatorUserId) return;
-  const now = Date.now();
-  sweep(now);
-  hints.set(key(channelType, botId, operatorUserId), now + TTL_MS);
-}
-
-/**
- * Single-use check: if a hint matches, returns true and removes the hint.
- * Returns false on miss or expired hint.
- */
-export function consumeTrustHint(channelType: string, botId: string, operatorUserId: string): boolean {
-  if (!operatorUserId) return false;
-  const now = Date.now();
-  sweep(now);
-  const k = key(channelType, botId, operatorUserId);
-  const expiresAt = hints.get(k);
-  if (expiresAt === undefined) return false;
-  hints.delete(k);
-  return true;
-}
-
-export function _resetTrustHintsForTest(): void {
-  hints.clear();
-}

package/src/claude-md-compose.migrate.test.ts

@@ -1,64 +0,0 @@
-/**
- * Coverage for migrateGroupsToClaudeLocal — operator-data-loss-prevention
- * helper that converts the pre-cutover `groups/<name>/CLAUDE.md` to the new
- * `CLAUDE.local.md` model and removes the obsolete `groups/global/` tree.
- * Three cases pinned: fresh install, existing legacy, both present.
- */
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-
-import { migrateGroupsToClaudeLocal } from './claude-md-compose.js';
-
-let tmp: string;
-let groupsDir: string;
-
-beforeEach(() => {
-  tmp = mkdtempSync(join(tmpdir(), 'paraclaw-groups-migrate-'));
-  groupsDir = join(tmp, 'groups');
-});
-
-afterEach(() => {
-  rmSync(tmp, { recursive: true, force: true });
-});
-
-describe('migrateGroupsToClaudeLocal', () => {
-  it('fresh install — groups dir absent — is a noop', () => {
-    migrateGroupsToClaudeLocal(groupsDir);
-    expect(existsSync(groupsDir)).toBe(false);
-  });
-
-  it('existing legacy — renames CLAUDE.md to CLAUDE.local.md, removes .claude-global.md and groups/global/', () => {
-    const fam = join(groupsDir, 'family-chat');
-    mkdirSync(fam, { recursive: true });
-    writeFileSync(join(fam, 'CLAUDE.md'), 'pre-cutover memory');
-    // Dangling symlink on the host, valid inside the container — match the real shape.
-    symlinkSync('/app/CLAUDE.md', join(fam, '.claude-global.md'));
-    mkdirSync(join(groupsDir, 'global'), { recursive: true });
-    writeFileSync(join(groupsDir, 'global', 'CLAUDE.md'), 'obsolete shared base');
-
-    migrateGroupsToClaudeLocal(groupsDir);
-
-    expect(existsSync(join(fam, 'CLAUDE.md'))).toBe(false);
-    expect(readFileSync(join(fam, 'CLAUDE.local.md'), 'utf8')).toBe('pre-cutover memory');
-    expect(existsSync(join(fam, '.claude-global.md'))).toBe(false);
-    expect(existsSync(join(groupsDir, 'global'))).toBe(false);
-  });
-
-  it('both present — preserves existing CLAUDE.local.md, drops legacy CLAUDE.md untouched', () => {
-    // Models the "first spawn already regenerated CLAUDE.md after a previous
-    // migration" branch: CLAUDE.local.md has the per-group memory; CLAUDE.md
-    // is the fresh composed entry — this path must skip the rename.
-    const fam = join(groupsDir, 'family-chat');
-    mkdirSync(fam, { recursive: true });
-    writeFileSync(join(fam, 'CLAUDE.md'), 'composed entry');
-    writeFileSync(join(fam, 'CLAUDE.local.md'), 'per-group memory');
-
-    migrateGroupsToClaudeLocal(groupsDir);
-
-    expect(readFileSync(join(fam, 'CLAUDE.md'), 'utf8')).toBe('composed entry');
-    expect(readFileSync(join(fam, 'CLAUDE.local.md'), 'utf8')).toBe('per-group memory');
-  });
-});

package/src/claude-md-compose.ts

@@ -1,205 +0,0 @@
-/**
- * CLAUDE.md composition for agent groups.
- *
- * Replaces the per-group "written once at init, owned by the group" pattern
- * with a host-regenerated entry point that imports:
- *   - a shared base (`container/CLAUDE.md` mounted RO at `/app/CLAUDE.md`)
- *   - optional per-skill fragments (skills that ship `instructions.md`)
- *   - optional per-MCP-server fragments (inline `instructions` field in
- *     `container.json`)
- *   - per-group agent memory (`CLAUDE.local.md`, auto-loaded by Claude Code)
- *
- * Runs on every spawn from `container-runner.buildMounts()`. Deterministic —
- * same inputs produce the same CLAUDE.md, and stale fragments are pruned.
- *
- * See `docs/claude-md-composition.md` for the full design.
- */
-import fs from 'fs';
-import path from 'path';
-
-import { GROUPS_DIR } from './config.js';
-import { readContainerConfig } from './container-config.js';
-import { log } from './log.js';
-import type { AgentGroup } from './types.js';
-
-// Symlink targets are container paths — dangling on host (hence the readlink
-// dance instead of existsSync), valid inside the container via RO mounts.
-const SHARED_CLAUDE_MD_CONTAINER_PATH = '/app/CLAUDE.md';
-const SHARED_SKILLS_CONTAINER_BASE = '/app/skills';
-const SHARED_MCP_TOOLS_CONTAINER_BASE = '/app/src/mcp-tools';
-
-// Host-side source paths used to discover fragment sources at compose time.
-// Resolved at call time (process.cwd() = project root) so tests can swap cwd.
-const MCP_TOOLS_HOST_SUBPATH = path.join('container', 'agent-runner', 'src', 'mcp-tools');
-
-const COMPOSED_HEADER = '<!-- Composed at spawn — do not edit. Edit CLAUDE.local.md for per-group content. -->';
-
-/**
- * Regenerate `groups/<folder>/CLAUDE.md` from the shared base, enabled skill
- * fragments, and MCP server fragments declared in `container.json`. Creates
- * an empty `CLAUDE.local.md` if missing.
- */
-export function composeGroupClaudeMd(group: AgentGroup): void {
-  const groupDir = path.resolve(GROUPS_DIR, group.folder);
-  if (!fs.existsSync(groupDir)) {
-    fs.mkdirSync(groupDir, { recursive: true });
-  }
-
-  const sharedLink = path.join(groupDir, '.claude-shared.md');
-  syncSymlink(sharedLink, SHARED_CLAUDE_MD_CONTAINER_PATH);
-
-  const fragmentsDir = path.join(groupDir, '.claude-fragments');
-  if (!fs.existsSync(fragmentsDir)) {
-    fs.mkdirSync(fragmentsDir, { recursive: true });
-  }
-
-  // Desired fragment set.
-  const config = readContainerConfig(group.folder);
-  const desired = new Map<string, { type: 'symlink' | 'inline'; content: string }>();
-
-  // Skill fragments — every skill that ships an `instructions.md`.
-  // TODO (shared-source refactor): respect `container.json` skill selection.
-  const skillsHostDir = path.join(process.cwd(), 'container', 'skills');
-  if (fs.existsSync(skillsHostDir)) {
-    for (const skillName of fs.readdirSync(skillsHostDir)) {
-      const hostFragment = path.join(skillsHostDir, skillName, 'instructions.md');
-      if (fs.existsSync(hostFragment)) {
-        desired.set(`skill-${skillName}.md`, {
-          type: 'symlink',
-          content: `${SHARED_SKILLS_CONTAINER_BASE}/${skillName}/instructions.md`,
-        });
-      }
-    }
-  }
-
-  // Built-in module fragments — every MCP tool source file that ships a
-  // sibling `<name>.instructions.md`. These describe how the agent should
-  // use that module's MCP tools (schedule_task, install_packages, etc.).
-  // Always included — these are built-in, not toggleable.
-  const mcpToolsHostDir = path.join(process.cwd(), MCP_TOOLS_HOST_SUBPATH);
-  if (fs.existsSync(mcpToolsHostDir)) {
-    for (const entry of fs.readdirSync(mcpToolsHostDir)) {
-      const match = entry.match(/^(.+)\.instructions\.md$/);
-      if (!match) continue;
-      const moduleName = match[1];
-      desired.set(`module-${moduleName}.md`, {
-        type: 'symlink',
-        content: `${SHARED_MCP_TOOLS_CONTAINER_BASE}/${entry}`,
-      });
-    }
-  }
-
-  // MCP server fragments — inline instructions from container.json for
-  // user-added external MCP servers.
-  for (const [name, mcp] of Object.entries(config.mcpServers)) {
-    if (mcp.instructions) {
-      desired.set(`mcp-${name}.md`, {
-        type: 'inline',
-        content: mcp.instructions,
-      });
-    }
-  }
-
-  // Reconcile: drop stale, write desired.
-  for (const existing of fs.readdirSync(fragmentsDir)) {
-    if (!desired.has(existing)) {
-      fs.unlinkSync(path.join(fragmentsDir, existing));
-    }
-  }
-  for (const [name, frag] of desired) {
-    const fragPath = path.join(fragmentsDir, name);
-    if (frag.type === 'symlink') {
-      syncSymlink(fragPath, frag.content);
-    } else {
-      writeAtomic(fragPath, frag.content);
-    }
-  }
-
-  // Composed entry — imports only.
-  const imports = ['@./.claude-shared.md'];
-  for (const name of [...desired.keys()].sort()) {
-    imports.push(`@./.claude-fragments/${name}`);
-  }
-  const body = [COMPOSED_HEADER, ...imports, ''].join('\n');
-  writeAtomic(path.join(groupDir, 'CLAUDE.md'), body);
-
-  const localFile = path.join(groupDir, 'CLAUDE.local.md');
-  if (!fs.existsSync(localFile)) {
-    fs.writeFileSync(localFile, '');
-  }
-}
-
-/**
- * One-time cutover from the `groups/global/CLAUDE.md` + `.claude-global.md`
- * pattern. Idempotent — safe to run on every host startup.
- *
- * For each group dir:
- *   - remove `.claude-global.md` symlink if present
- *   - rename `CLAUDE.md` → `CLAUDE.local.md` (only if `CLAUDE.local.md`
- *     doesn't already exist — preserves pre-cutover content as per-group
- *     memory; after the first spawn regenerates `CLAUDE.md`, this branch
- *     is skipped because `CLAUDE.local.md` now exists)
- *
- * Globally:
- *   - delete `groups/global/` (content already in `container/CLAUDE.md`)
- */
-export function migrateGroupsToClaudeLocal(groupsDir: string = GROUPS_DIR): void {
-  if (!fs.existsSync(groupsDir)) return;
-
-  const actions: string[] = [];
-
-  for (const entry of fs.readdirSync(groupsDir, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    if (entry.name === 'global') continue;
-
-    const groupDir = path.join(groupsDir, entry.name);
-
-    const oldGlobalLink = path.join(groupDir, '.claude-global.md');
-    try {
-      fs.lstatSync(oldGlobalLink);
-      fs.unlinkSync(oldGlobalLink);
-      actions.push(`${entry.name}/.claude-global.md removed`);
-    } catch {
-      /* already gone */
-    }
-
-    const claudeMd = path.join(groupDir, 'CLAUDE.md');
-    const claudeLocal = path.join(groupDir, 'CLAUDE.local.md');
-    if (fs.existsSync(claudeMd) && !fs.existsSync(claudeLocal)) {
-      fs.renameSync(claudeMd, claudeLocal);
-      actions.push(`${entry.name}/CLAUDE.md → CLAUDE.local.md`);
-    }
-  }
-
-  const globalDir = path.join(groupsDir, 'global');
-  if (fs.existsSync(globalDir)) {
-    fs.rmSync(globalDir, { recursive: true, force: true });
-    actions.push('groups/global/ removed');
-  }
-
-  if (actions.length > 0) {
-    log.info('Migrated groups to CLAUDE.local.md model', { actions });
-  }
-}
-
-function syncSymlink(linkPath: string, target: string): void {
-  let currentTarget: string | null = null;
-  try {
-    currentTarget = fs.readlinkSync(linkPath);
-  } catch {
-    /* missing */
-  }
-  if (currentTarget === target) return;
-  try {
-    fs.unlinkSync(linkPath);
-  } catch {
-    /* missing */
-  }
-  fs.symlinkSync(target, linkPath);
-}
-
-function writeAtomic(filePath: string, content: string): void {
-  const tmp = `${filePath}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, content);
-  fs.renameSync(tmp, filePath);
-}