@openparachute/agent 0.1.0

package/src/delivery.ts

@@ -0,0 +1,445 @@
+/**
+ * Outbound message delivery.
+ * Polls session outbound DBs for undelivered messages, delivers through channel adapters.
+ *
+ * Two-DB architecture:
+ *   - Reads messages_out from outbound.db (container-owned, opened read-only)
+ *   - Tracks delivery in inbound.db's `delivered` table (host-owned)
+ *   - Never writes to outbound.db — preserves single-writer-per-file invariant
+ */
+import type { Database } from './db/connection.js';
+
+import { getActivitySyncedSeq, mergeActivityBatch } from './db/agent-activity.js';
+import { getRunningSessions, getActiveSessions, createApproval } from './db/sessions.js';
+import { getAgentGroup } from './db/agent-groups.js';
+import { getDb, hasTable } from './db/connection.js';
+import { getMessagingGroupByPlatform } from './db/messaging-groups.js';
+import {
+  getDueOutboundMessages,
+  getDeliveredIds,
+  getOutboundActivity,
+  markDelivered,
+  markDeliveryFailed,
+  migrateDeliveredTable,
+} from './db/session-db.js';
+import { log } from './log.js';
+import { normalizeOptions } from './channels/ask-question.js';
+import { clearOutbox, openInboundDb, openOutboundDb, readOutboxFiles } from './session-manager.js';
+import { pauseTypingRefreshAfterDelivery, setTypingAdapter } from './modules/typing/index.js';
+import type { OutboundFile } from './channels/adapter.js';
+import type { Session } from './types.js';
+
+const ACTIVE_POLL_MS = 1000;
+const SWEEP_POLL_MS = 60_000;
+const MAX_DELIVERY_ATTEMPTS = 3;
+
+/** Track delivery attempt counts. Resets on process restart (gives failed messages a fresh chance). */
+const deliveryAttempts = new Map<string, number>();
+
+/**
+ * Sessions whose outbound queue is currently being drained.
+ *
+ * The active poll (1s, running sessions) and the sweep poll (60s, all
+ * active sessions) both call deliverSessionMessages, and a running session
+ * is in *both* result sets. Without this guard, the two timer chains can
+ * race on the same outbound row: both read it as undelivered, both call
+ * the channel adapter, both markDelivered (idempotent in the DB via
+ * INSERT OR IGNORE — but the user has already seen the message twice).
+ *
+ * Skipping (vs. queueing) is correct: any message left over when the
+ * second caller skips will be picked up on the next poll tick (~1s).
+ */
+const inflightDeliveries = new Set<string>();
+
+export interface ChannelDeliveryAdapter {
+  deliver(
+    channelType: string,
+    platformId: string,
+    threadId: string | null,
+    kind: string,
+    content: string,
+    files?: OutboundFile[],
+  ): Promise<string | undefined>;
+  setTyping?(channelType: string, platformId: string, threadId: string | null): Promise<void>;
+}
+
+let deliveryAdapter: ChannelDeliveryAdapter | null = null;
+let activePolling = false;
+let sweepPolling = false;
+
+/**
+ * Callbacks fired when the delivery adapter is first set (and again if it's
+ * replaced). Lets modules that need the adapter at boot hook in without core
+ * calling into the module directly.
+ *
+ * Not a general-purpose registry — narrow lifecycle hook only.
+ */
+type AdapterReadyCallback = (adapter: ChannelDeliveryAdapter) => void | Promise<void>;
+const adapterReadyCallbacks: AdapterReadyCallback[] = [];
+
+/** Current delivery adapter or null if not yet set. Modules use this in live
+ *  message-flow handlers where the adapter is guaranteed to be set. For
+ *  boot-time setup (before the adapter is ready), use onDeliveryAdapterReady. */
+export function getDeliveryAdapter(): ChannelDeliveryAdapter | null {
+  return deliveryAdapter;
+}
+
+export function onDeliveryAdapterReady(cb: AdapterReadyCallback): void {
+  adapterReadyCallbacks.push(cb);
+  if (deliveryAdapter) {
+    // Already set — fire immediately so late registrations still run.
+    void Promise.resolve()
+      .then(() => cb(deliveryAdapter as ChannelDeliveryAdapter))
+      .catch((err) => log.error('onDeliveryAdapterReady callback threw', { err }));
+  }
+}
+
+export function setDeliveryAdapter(adapter: ChannelDeliveryAdapter): void {
+  deliveryAdapter = adapter;
+  // Forward to the typing module so it can fire setTyping on its own
+  // interval. Direct call, not a registry — typing is a default module.
+  setTypingAdapter(adapter);
+  for (const cb of adapterReadyCallbacks) {
+    void Promise.resolve()
+      .then(() => cb(adapter))
+      .catch((err) => log.error('onDeliveryAdapterReady callback threw', { err }));
+  }
+}
+
+/** Start the active container poll loop (~1s). */
+export function startActiveDeliveryPoll(): void {
+  if (activePolling) return;
+  activePolling = true;
+  pollActive();
+}
+
+/** Start the sweep poll loop (~60s). */
+export function startSweepDeliveryPoll(): void {
+  if (sweepPolling) return;
+  sweepPolling = true;
+  pollSweep();
+}
+
+async function pollActive(): Promise<void> {
+  if (!activePolling) return;
+
+  try {
+    const sessions = getRunningSessions();
+    for (const session of sessions) {
+      await deliverSessionMessages(session);
+    }
+  } catch (err) {
+    log.error('Active delivery poll error', { err });
+  }
+
+  setTimeout(pollActive, ACTIVE_POLL_MS);
+}
+
+async function pollSweep(): Promise<void> {
+  if (!sweepPolling) return;
+
+  try {
+    const sessions = getActiveSessions();
+    for (const session of sessions) {
+      await deliverSessionMessages(session);
+    }
+  } catch (err) {
+    log.error('Sweep delivery poll error', { err });
+  }
+
+  setTimeout(pollSweep, SWEEP_POLL_MS);
+}
+
+export async function deliverSessionMessages(session: Session): Promise<void> {
+  // Reject re-entry from a concurrent poll on the same session — see the
+  // comment on inflightDeliveries above.
+  if (inflightDeliveries.has(session.id)) return;
+  inflightDeliveries.add(session.id);
+
+  try {
+    await drainSession(session);
+  } finally {
+    inflightDeliveries.delete(session.id);
+  }
+}
+
+async function drainSession(session: Session): Promise<void> {
+  const agentGroup = getAgentGroup(session.agent_group_id);
+  if (!agentGroup) return;
+
+  let outDb: Database;
+  let inDb: Database;
+  try {
+    outDb = openOutboundDb(agentGroup.id, session.id);
+    inDb = openInboundDb(agentGroup.id, session.id);
+  } catch {
+    return; // DBs might not exist yet
+  }
+
+  try {
+    // Drain any new activity rows from outbound.db into central agent_activity.
+    // Independent of message delivery — activity should be visible even when
+    // there are no outbound messages. Cheap on idle sessions: a single indexed
+    // SELECT > cursor returning zero rows.
+    try {
+      const sinceSeq = getActivitySyncedSeq(session.id);
+      const activityRows = getOutboundActivity(outDb, sinceSeq);
+      if (activityRows.length > 0) {
+        mergeActivityBatch(session.agent_group_id, session.id, activityRows);
+      }
+    } catch (err) {
+      log.warn('activity merge failed', { sessionId: session.id, err });
+    }
+
+    // Read all due messages from outbound.db (read-only)
+    const allDue = getDueOutboundMessages(outDb);
+    if (allDue.length === 0) return;
+
+    // Filter out already-delivered messages using inbound.db's delivered table
+    const delivered = getDeliveredIds(inDb);
+    const undelivered = allDue.filter((m) => !delivered.has(m.id));
+    if (undelivered.length === 0) return;
+
+    // Ensure platform_message_id column exists (migration for existing sessions)
+    migrateDeliveredTable(inDb);
+
+    for (const msg of undelivered) {
+      try {
+        const platformMsgId = await deliverMessage(msg, session, inDb);
+        markDelivered(inDb, msg.id, platformMsgId ?? null);
+        deliveryAttempts.delete(msg.id);
+
+        // Pause the typing indicator after a real user-facing message
+        // lands on the user's screen, so the client has time to visually
+        // clear the indicator before the next heartbeat tick brings it
+        // back. Skip the pause for internal traffic (system actions,
+        // agent-to-agent routing) — the user doesn't see those and
+        // shouldn't get a gap in their typing indicator for them.
+        if (msg.kind !== 'system' && msg.channel_type !== 'agent') {
+          pauseTypingRefreshAfterDelivery(session.id);
+        }
+      } catch (err) {
+        const attempts = (deliveryAttempts.get(msg.id) ?? 0) + 1;
+        deliveryAttempts.set(msg.id, attempts);
+        if (attempts >= MAX_DELIVERY_ATTEMPTS) {
+          log.error('Message delivery failed permanently, giving up', {
+            messageId: msg.id,
+            sessionId: session.id,
+            attempts,
+            err,
+          });
+          markDeliveryFailed(inDb, msg.id);
+          deliveryAttempts.delete(msg.id);
+        } else {
+          log.warn('Message delivery failed, will retry', {
+            messageId: msg.id,
+            sessionId: session.id,
+            attempt: attempts,
+            maxAttempts: MAX_DELIVERY_ATTEMPTS,
+            err,
+          });
+        }
+      }
+    }
+  } finally {
+    outDb.close();
+    inDb.close();
+  }
+}
+
+async function deliverMessage(
+  msg: {
+    id: string;
+    kind: string;
+    platform_id: string | null;
+    channel_type: string | null;
+    thread_id: string | null;
+    content: string;
+  },
+  session: Session,
+  inDb: Database,
+): Promise<string | undefined> {
+  if (!deliveryAdapter) {
+    log.warn('No delivery adapter configured, dropping message', { id: msg.id });
+    return;
+  }
+
+  const content = JSON.parse(msg.content);
+
+  // System actions — handle internally (schedule_task, cancel_task, etc.)
+  if (msg.kind === 'system') {
+    await handleSystemAction(content, session, inDb);
+    return;
+  }
+
+  // Agent-to-agent — route to target session via the agent-to-agent module.
+  // Guarded by the channel_type check. If the module isn't installed the
+  // `agent_destinations` table won't exist and `routeAgentMessage`'s permission
+  // check will throw, which falls into the normal retry → mark-failed path.
+  if (msg.channel_type === 'agent') {
+    if (!hasTable(getDb(), 'agent_destinations')) {
+      throw new Error(`agent-to-agent module not installed — cannot route message ${msg.id}`);
+    }
+    const { routeAgentMessage } = await import('./modules/agent-to-agent/agent-route.js');
+    await routeAgentMessage(msg, session);
+    return;
+  }
+
+  // Permission check: the source agent must be allowed to deliver to this
+  // channel destination. Two ways it passes:
+  //
+  //   1. The target is the session's own origin chat (session.messaging_group_id
+  //      matches). An agent can always reply to the chat it was spawned from;
+  //      requiring a destinations row for the obvious case is a footgun.
+  //
+  //   2. Otherwise, the agent must have an explicit agent_destinations row
+  //      targeting that messaging group. createMessagingGroupAgent() inserts
+  //      these automatically when wiring, so an operator wiring additional
+  //      chats to the agent doesn't need a separate ACL step.
+  //
+  // Failures throw — unlike a silent `return`, an Error falls into the retry
+  // path in deliverSessionMessages and eventually marks the message as failed
+  // (instead of marking it delivered when nothing was actually delivered,
+  // which was the pre-refactor bug).
+  if (msg.channel_type && msg.platform_id) {
+    const mg = getMessagingGroupByPlatform(msg.channel_type, msg.platform_id);
+    if (!mg) {
+      throw new Error(`unknown messaging group for ${msg.channel_type}/${msg.platform_id} (message ${msg.id})`);
+    }
+    const isOriginChat = session.messaging_group_id === mg.id;
+    // Guarded: without the agent-to-agent module, `agent_destinations`
+    // doesn't exist and we permit all non-origin channel sends (the
+    // origin-chat case is always allowed regardless). Inlined SQL instead
+    // of importing `hasDestination` so core doesn't depend on the module.
+    if (!isOriginChat && hasTable(getDb(), 'agent_destinations')) {
+      const row = getDb()
+        .prepare(
+          'SELECT 1 FROM agent_destinations WHERE agent_group_id = ? AND target_type = ? AND target_id = ? LIMIT 1',
+        )
+        .get(session.agent_group_id, 'channel', mg.id);
+      if (!row) {
+        throw new Error(
+          `unauthorized channel destination: ${session.agent_group_id} cannot send to ${mg.channel_type}/${mg.platform_id}`,
+        );
+      }
+    }
+  }
+
+  // Track pending questions for ask_user_question flow as kind='question'
+  // rows in the unified `approvals` table. Guarded: without the interactive
+  // module's migration, `approvals` doesn't exist and we skip persistence —
+  // the card still delivers, but the response path has nowhere to land.
+  if (content.type === 'ask_question' && content.questionId && hasTable(getDb(), 'approvals')) {
+    const title = content.title as string | undefined;
+    const rawOptions = content.options as unknown;
+    if (!title || !Array.isArray(rawOptions)) {
+      log.error('ask_question missing required title/options — not persisting', {
+        questionId: content.questionId,
+      });
+    } else {
+      const inserted = createApproval({
+        id: content.questionId as string,
+        kind: 'question',
+        agent_group_id: session.agent_group_id,
+        session_id: session.id,
+        body: {
+          title,
+          options: normalizeOptions(rawOptions as never),
+          message_out_id: msg.id,
+          platform_id: msg.platform_id,
+          channel_type: msg.channel_type,
+          thread_id: msg.thread_id,
+        },
+        created_at: new Date().toISOString(),
+      });
+      if (inserted) {
+        log.info('Pending question created', { questionId: content.questionId, sessionId: session.id });
+      }
+    }
+  }
+
+  // Channel delivery
+  if (!msg.channel_type || !msg.platform_id) {
+    log.warn('Message missing routing fields', { id: msg.id });
+    return;
+  }
+
+  // Read file attachments from outbox if the content declares files.
+  // File I/O lives in session-manager.ts (symmetric with inbound
+  // extractAttachmentFiles) — delivery just hands buffers to the adapter.
+  const files =
+    Array.isArray(content.files) && content.files.length > 0
+      ? readOutboxFiles(session.agent_group_id, session.id, msg.id, content.files as string[])
+      : undefined;
+
+  const platformMsgId = await deliveryAdapter.deliver(
+    msg.channel_type,
+    msg.platform_id,
+    msg.thread_id,
+    msg.kind,
+    msg.content,
+    files,
+  );
+  log.info('Message delivered', {
+    id: msg.id,
+    channelType: msg.channel_type,
+    platformId: msg.platform_id,
+    platformMsgId,
+    fileCount: files?.length,
+  });
+
+  clearOutbox(session.agent_group_id, session.id, msg.id);
+
+  return platformMsgId;
+}
+
+/**
+ * Delivery action registry.
+ *
+ * Modules register handlers for system-kind outbound message actions via
+ * `registerDeliveryAction`. Core checks the registry first in
+ * `handleSystemAction` and falls through to the inline switch when no
+ * handler is registered. The switch will shrink as modules are extracted
+ * (scheduling, approvals, agent-to-agent) and eventually only its default
+ * branch remains.
+ *
+ * Default when no handler registered and the switch doesn't match: log
+ * "Unknown system action" and return.
+ */
+export type DeliveryActionHandler = (
+  content: Record<string, unknown>,
+  session: Session,
+  inDb: Database,
+) => Promise<void>;
+
+const actionHandlers = new Map<string, DeliveryActionHandler>();
+
+export function registerDeliveryAction(action: string, handler: DeliveryActionHandler): void {
+  if (actionHandlers.has(action)) {
+    log.warn('Delivery action handler overwritten', { action });
+  }
+  actionHandlers.set(action, handler);
+}
+
+/**
+ * Handle system actions from the container agent.
+ * These are written to messages_out because the container can't write to inbound.db.
+ * The host applies them to inbound.db here.
+ */
+async function handleSystemAction(content: Record<string, unknown>, session: Session, inDb: Database): Promise<void> {
+  const action = content.action as string;
+  log.info('System action from agent', { sessionId: session.id, action });
+
+  const registered = actionHandlers.get(action);
+  if (registered) {
+    await registered(content, session, inDb);
+    return;
+  }
+
+  log.warn('Unknown system action', { action });
+}
+
+export function stopDeliveryPolls(): void {
+  activePolling = false;
+  sweepPolling = false;
+}

package/src/env.ts

@@ -0,0 +1,74 @@
+import fs from 'fs';
+import path from 'path';
+import { log } from './log.js';
+
+/**
+ * Read an env var by its current name, falling back to a legacy name
+ * (with a one-shot deprecation warning) when only the old name is set.
+ *
+ * Used for the paraclaw → parachute-agent env var rename in 0.1.0:
+ * existing `.env` files and operator scripts still reference `PARACLAW_*`
+ * names; we accept those for one cycle but warn so operators have a
+ * window to update before 0.2.0 drops the compat read.
+ *
+ * One-shot per-legacy-name dedupe: each legacy name warns at most once
+ * per process lifetime, so a value read on every request (e.g. inside
+ * a Connect middleware) doesn't spam the log.
+ *
+ * Resolution order, matching the wider PARACHUTE_HOME pattern: explicit
+ * fresh override wins, then legacy (with warning), then undefined.
+ */
+const seenLegacyEnvWarnings = new Set<string>();
+
+export function readEnvWithLegacy(fresh: string, legacy: string): string | undefined {
+  const freshVal = process.env[fresh];
+  if (freshVal !== undefined) return freshVal;
+  const legacyVal = process.env[legacy];
+  if (legacyVal !== undefined) {
+    if (!seenLegacyEnvWarnings.has(legacy)) {
+      seenLegacyEnvWarnings.add(legacy);
+      log.warn(`Deprecated env var ${legacy} — rename to ${fresh}. Compat read removed in 0.2.0.`);
+    }
+    return legacyVal;
+  }
+  return undefined;
+}
+
+/**
+ * Parse the .env file and return values for the requested keys.
+ * Does NOT load anything into process.env — callers decide what to
+ * do with the values. This keeps secrets out of the process environment
+ * so they don't leak to child processes.
+ */
+export function readEnvFile(keys: string[]): Record<string, string> {
+  const envFile = path.join(process.cwd(), '.env');
+  let content: string;
+  try {
+    content = fs.readFileSync(envFile, 'utf-8');
+  } catch (err) {
+    log.debug('.env file not found, using defaults', { err });
+    return {};
+  }
+
+  const result: Record<string, string> = {};
+  const wanted = new Set(keys);
+
+  for (const line of content.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = trimmed.slice(0, eqIdx).trim();
+    if (!wanted.has(key)) continue;
+    let value = trimmed.slice(eqIdx + 1).trim();
+    if (
+      value.length >= 2 &&
+      ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (value) result[key] = value;
+  }
+
+  return result;
+}

package/src/group-folder.test.ts

@@ -0,0 +1,35 @@
+import path from 'path';
+
+import { describe, expect, it } from 'vitest';
+
+import { isValidGroupFolder, resolveGroupFolderPath, resolveGroupIpcPath } from './group-folder.js';
+
+describe('group folder validation', () => {
+  it('accepts normal group folder names', () => {
+    expect(isValidGroupFolder('main')).toBe(true);
+    expect(isValidGroupFolder('family-chat')).toBe(true);
+    expect(isValidGroupFolder('Team_42')).toBe(true);
+  });
+
+  it('rejects traversal and reserved names', () => {
+    expect(isValidGroupFolder('../../etc')).toBe(false);
+    expect(isValidGroupFolder('/tmp')).toBe(false);
+    expect(isValidGroupFolder('global')).toBe(false);
+    expect(isValidGroupFolder('')).toBe(false);
+  });
+
+  it('resolves safe paths under groups directory', () => {
+    const resolved = resolveGroupFolderPath('family-chat');
+    expect(resolved.endsWith(`${path.sep}groups${path.sep}family-chat`)).toBe(true);
+  });
+
+  it('resolves safe paths under data ipc directory', () => {
+    const resolved = resolveGroupIpcPath('family-chat');
+    expect(resolved.endsWith(`${path.sep}data${path.sep}ipc${path.sep}family-chat`)).toBe(true);
+  });
+
+  it('throws for unsafe folder names', () => {
+    expect(() => resolveGroupFolderPath('../../etc')).toThrow();
+    expect(() => resolveGroupIpcPath('/tmp')).toThrow();
+  });
+});

package/src/group-folder.ts

@@ -0,0 +1,44 @@
+import path from 'path';
+
+import { DATA_DIR, GROUPS_DIR } from './config.js';
+
+const GROUP_FOLDER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+const RESERVED_FOLDERS = new Set(['global']);
+
+export function isValidGroupFolder(folder: string): boolean {
+  if (!folder) return false;
+  if (folder !== folder.trim()) return false;
+  if (!GROUP_FOLDER_PATTERN.test(folder)) return false;
+  if (folder.includes('/') || folder.includes('\\')) return false;
+  if (folder.includes('..')) return false;
+  if (RESERVED_FOLDERS.has(folder.toLowerCase())) return false;
+  return true;
+}
+
+export function assertValidGroupFolder(folder: string): void {
+  if (!isValidGroupFolder(folder)) {
+    throw new Error(`Invalid group folder "${folder}"`);
+  }
+}
+
+function ensureWithinBase(baseDir: string, resolvedPath: string): void {
+  const rel = path.relative(baseDir, resolvedPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`Path escapes base directory: ${resolvedPath}`);
+  }
+}
+
+export function resolveGroupFolderPath(folder: string): string {
+  assertValidGroupFolder(folder);
+  const groupPath = path.resolve(GROUPS_DIR, folder);
+  ensureWithinBase(GROUPS_DIR, groupPath);
+  return groupPath;
+}
+
+export function resolveGroupIpcPath(folder: string): string {
+  assertValidGroupFolder(folder);
+  const ipcBaseDir = path.resolve(DATA_DIR, 'ipc');
+  const ipcPath = path.resolve(ipcBaseDir, folder);
+  ensureWithinBase(ipcBaseDir, ipcPath);
+  return ipcPath;
+}

package/src/group-init.ts

@@ -0,0 +1,92 @@
+import fs from 'fs';
+import path from 'path';
+
+import { DATA_DIR, GROUPS_DIR } from './config.js';
+import { initContainerConfig } from './container-config.js';
+import { log } from './log.js';
+import type { AgentGroup } from './types.js';
+
+const DEFAULT_SETTINGS_JSON =
+  JSON.stringify(
+    {
+      env: {
+        CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+        CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '1',
+        CLAUDE_CODE_DISABLE_AUTO_MEMORY: '0',
+      },
+    },
+    null,
+    2,
+  ) + '\n';
+
+/**
+ * Initialize the on-disk filesystem state for an agent group. Idempotent —
+ * every step is gated on the target not already existing, so re-running on
+ * an already-initialized group is a no-op.
+ *
+ * Called once per group lifetime at creation, or defensively from
+ * `buildMounts()` for groups that pre-date this code path.
+ *
+ * Source code and skills are shared RO mounts — not copied per-group.
+ * Skill symlinks are synced at spawn time by container-runner.ts.
+ *
+ * The composed `CLAUDE.md` is NOT written here — it's regenerated on every
+ * spawn by `composeGroupClaudeMd()` (see `claude-md-compose.ts`). Initial
+ * per-group instructions (if provided) seed `CLAUDE.local.md`.
+ */
+export function initGroupFilesystem(group: AgentGroup, opts?: { instructions?: string }): void {
+  const initialized: string[] = [];
+
+  // 1. groups/<folder>/ — group memory + working dir
+  const groupDir = path.resolve(GROUPS_DIR, group.folder);
+  if (!fs.existsSync(groupDir)) {
+    fs.mkdirSync(groupDir, { recursive: true });
+    initialized.push('groupDir');
+  }
+
+  // groups/<folder>/CLAUDE.local.md — per-group agent memory, auto-loaded by
+  // Claude Code. Seeded with caller-provided instructions on first creation.
+  const claudeLocalFile = path.join(groupDir, 'CLAUDE.local.md');
+  if (!fs.existsSync(claudeLocalFile)) {
+    const body = opts?.instructions ? opts.instructions + '\n' : '';
+    fs.writeFileSync(claudeLocalFile, body);
+    initialized.push('CLAUDE.local.md');
+  }
+
+  // groups/<folder>/container.json — empty container config, replaces the
+  // former agent_groups.container_config DB column. Self-modification flows
+  // read and write this file directly.
+  if (initContainerConfig(group.folder)) {
+    initialized.push('container.json');
+  }
+
+  // 2. data/sessions/<id>/.claude-shared/ — Claude state + per-group skills
+  const claudeDir = path.join(DATA_DIR, 'sessions', group.id, '.claude-shared');
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+    initialized.push('.claude-shared');
+  }
+
+  const settingsFile = path.join(claudeDir, 'settings.json');
+  if (!fs.existsSync(settingsFile)) {
+    fs.writeFileSync(settingsFile, DEFAULT_SETTINGS_JSON);
+    initialized.push('settings.json');
+  }
+
+  // Skills directory — created empty here; symlinks are synced at spawn
+  // time by container-runner.ts based on container.json skills selection.
+  const skillsDst = path.join(claudeDir, 'skills');
+  if (!fs.existsSync(skillsDst)) {
+    fs.mkdirSync(skillsDst, { recursive: true });
+    initialized.push('skills/');
+  }
+
+  if (initialized.length > 0) {
+    log.info('Initialized group filesystem', {
+      group: group.name,
+      folder: group.folder,
+      id: group.id,
+      steps: initialized,
+    });
+  }
+}