create-ironclaws 1.0.0

package/template/src/container-runner.ts

@@ -0,0 +1,1029 @@
+/**
+ * Container Runner for NanoClaw
+ * Spawns agent execution in containers and handles IPC
+ */
+import { ChildProcess, exec, spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+
+import YAML from 'yaml';
+import { applyContainerIptables, cleanupContainerIptables, getContainerIp } from './network-policy.js';
+import {
+  CONTAINER_IMAGE,
+  CONTAINER_MAX_OUTPUT_SIZE,
+  CONTAINER_TIMEOUT,
+  DATA_DIR,
+  GROUPS_DIR,
+  IDLE_TIMEOUT,
+  ONECLI_URL,
+  TIMEZONE,
+} from './config.js';
+import { resolveGroupFolderPath, resolveGroupIpcPath } from './group-folder.js';
+import { logger } from './logger.js';
+import {
+  CONTAINER_RUNTIME_BIN,
+  hostGatewayArgs,
+  readonlyMountArgs,
+  stopContainer,
+} from './container-runtime.js';
+import { OneCLI } from '@onecli-sh/sdk';
+import { generateGitHubToken } from './github-token.js';
+import { generateGoogleAccessToken } from './google-token.js';
+import { validateAdditionalMounts } from './mount-security.js';
+import { RegisteredGroup } from './types.js';
+import { ensureWorktree } from './worktree.js';
+import { readEnvFile } from './env.js';
+
+// Patterns that identify sensitive env var keys — used to redact values from logs.
+const SENSITIVE_KEY_PATTERNS = [
+  'TOKEN', 'SECRET', 'KEY', 'PASSWORD', 'CREDENTIAL', 'PEM', 'AUTH',
+];
+
+const CREDENTIALS_FILE = path.resolve(process.cwd(), "agent-credentials.yaml");
+interface CredentialsConfig { common: { config: string[]; skills?: string[]; tools?: string[] }; agents: Record<string, { config: string[]; skills?: string[]; tools?: string[] }>; }
+let _cc: CredentialsConfig | null = null;
+function loadCredentialsConfig(): CredentialsConfig {
+  if (_cc) return _cc;
+  try {
+    _cc = YAML.parse(fs.readFileSync(CREDENTIALS_FILE, "utf-8")) as CredentialsConfig;
+    return _cc;
+  } catch (err) {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      // File exists but failed to parse — this is a real error, not a missing file.
+      logger.error({ file: CREDENTIALS_FILE, err }, 'agent-credentials.yaml exists but failed to parse — fix the YAML before spawning agents');
+      throw new Error(`Failed to parse ${CREDENTIALS_FILE}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // File doesn't exist — warn once and use empty config (valid for fresh setups).
+    logger.warn({ file: CREDENTIALS_FILE }, 'agent-credentials.yaml not found — no per-agent credential scoping applied');
+    return { common: { config: [] }, agents: {} };
+  }
+}
+function getAgentEnvKeys(gf: string): string[] {
+  const c = loadCredentialsConfig();
+  if (!c.common.config.length) return FORWARDED_ENV_KEYS;
+  return [...c.common.config, ...(c.agents[gf]?.config || [])];
+}
+
+function getAgentSkills(gf: string): string[] | null {
+  const c = loadCredentialsConfig();
+  // If neither common nor agent has skills config, return null (copy all — legacy fallback)
+  if (!c.common.skills && !c.agents[gf]?.skills) return null;
+  const common = c.common.skills || [];
+  const agentExtra = c.agents[gf]?.skills || [];
+  return [...common, ...agentExtra];
+}
+
+/**
+ * Returns the list of tool filenames this agent is allowed to use.
+ * Returns null if no tools config defined (legacy fallback — use baked-in image tools).
+ */
+function getAgentTools(gf: string): string[] | null {
+  const c = loadCredentialsConfig();
+  const agentCfg = c.agents[gf];
+  if (!agentCfg || !('tools' in agentCfg)) return null;
+  const common = c.common.tools || [];
+  const agentTools = agentCfg.tools || [];
+  return [...common, ...agentTools];
+}
+
+/**
+ * Build a per-agent tools directory containing only the allowed tool files.
+ * This directory is mounted over /workspace/extra/tools to shadow the
+ * baked-in image tools. Returns the host path to mount.
+ */
+function buildAgentToolsDir(groupFolder: string, allowedTools: string[]): string {
+  const toolsSrc = path.join(process.cwd(), 'container', 'tools');
+  const toolsDst = path.join(DATA_DIR, 'tools', groupFolder);
+  fs.mkdirSync(toolsDst, { recursive: true });
+
+  // Remove any tool files no longer allowed
+  if (fs.existsSync(toolsDst)) {
+    for (const existing of fs.readdirSync(toolsDst)) {
+      if (!allowedTools.includes(existing)) {
+        fs.rmSync(path.join(toolsDst, existing), { force: true });
+      }
+    }
+  }
+
+  // Copy allowed tools (only if changed)
+  for (const toolFile of allowedTools) {
+    const src = path.join(toolsSrc, toolFile);
+    const dst = path.join(toolsDst, toolFile);
+    if (!fs.existsSync(src)) continue;
+    const srcMtime = fs.statSync(src).mtimeMs;
+    const dstMtime = fs.existsSync(dst) ? fs.statSync(dst).mtimeMs : 0;
+    if (srcMtime > dstMtime) {
+      fs.copyFileSync(src, dst);
+    }
+  }
+
+  return toolsDst;
+}
+
+/**
+ * Redact sensitive `-e KEY=VALUE` pairs from container args for safe logging.
+ * Returns a new string with secret values replaced by `***`.
+ */
+function redactContainerArgs(args: string[]): string {
+  const redacted: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '-e' && i + 1 < args.length) {
+      const envPair = args[i + 1];
+      const eqIdx = envPair.indexOf('=');
+      if (eqIdx !== -1) {
+        const key = envPair.slice(0, eqIdx).toUpperCase();
+        if (SENSITIVE_KEY_PATTERNS.some((p) => key.includes(p))) {
+          redacted.push('-e', `${envPair.slice(0, eqIdx)}=***`);
+          i++; // skip the value arg
+          continue;
+        }
+      }
+      redacted.push(args[i], args[i + 1]);
+      i++;
+    } else {
+      redacted.push(args[i]);
+    }
+  }
+  return redacted.join(' ');
+}
+
+// Env vars forwarded from .env into every container so Claude's Bash tool
+// can call service-specific tools (elastic_query.py, gh, etc.) without
+// secrets being baked into the container image.
+const FORWARDED_ENV_KEYS = [
+  'CLAUDE_CODE_API_KEY_HELPER_TTL_MS',
+  'ANTHROPIC_BASE_URL',
+  'ANTHROPIC_BEDROCK_BASE_URL',
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_MODEL',
+  'ANTHROPIC_SMALL_FAST_MODEL',
+  'ANTHROPIC_DEFAULT_SONNET_MODEL',
+  'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL',
+
+  'CLAUDE_CODE_SKIP_BEDROCK_AUTH',
+  'CLAUDE_CODE_USE_BEDROCK',
+  'ELASTIC_API_KEY',
+  'ELASTIC_BASE_URL',
+  'ELASTIC_NAMESPACES',
+  'ELASTIC_STAGING_NAMESPACES',
+  'ELASTIC_LOOKBACK_MINUTES',
+  'ELASTIC_MAX_LOGS',
+  'GITHUB_TOKEN',
+  'GITHUB_REPO',
+
+  // Jira (ticket-creator, jira-worker)
+  'JIRA_BASE_URL',
+  'JIRA_EMAIL',
+  'JIRA_API_TOKEN',
+  'JIRA_PROJECT_KEY',
+
+  // Google Drive (byte standup agent)
+  'GOOGLE_CLIENT_ID',
+  'GOOGLE_CLIENT_SECRET',
+  'GOOGLE_REFRESH_TOKEN',
+  'GOOGLE_DRIVE_STANDUP_FOLDER_ID',
+
+  // Slack (byte it-internal channel history tool)
+  'SLACK_BOT_TOKEN',
+];
+
+const onecli = new OneCLI({ url: ONECLI_URL });
+
+// Sentinel markers for robust output parsing (must match agent-runner)
+const OUTPUT_START_MARKER = '---NANOCLAW_OUTPUT_START---';
+const OUTPUT_END_MARKER = '---NANOCLAW_OUTPUT_END---';
+
+export interface ContainerInput {
+  prompt: string;
+  sessionId?: string;
+  groupFolder: string;
+  chatJid: string;
+  isMain: boolean;
+  isScheduledTask?: boolean;
+  assistantName?: string;
+  script?: string;
+  senderEmail?: string;
+}
+
+export interface ContainerOutput {
+  status: 'success' | 'error';
+  result: string | null;
+  newSessionId?: string;
+  error?: string;
+}
+
+interface VolumeMount {
+  hostPath: string;
+  containerPath: string;
+  readonly: boolean;
+}
+
+async function buildVolumeMounts(
+  group: RegisteredGroup,
+  isMain: boolean,
+): Promise<VolumeMount[]> {
+  const mounts: VolumeMount[] = [];
+  const projectRoot = process.cwd();
+  const groupDir = resolveGroupFolderPath(group.folder);
+
+  if (isMain) {
+    // Main gets the project root read-only. Writable paths the agent needs
+    // (group folder, IPC, .claude/) are mounted separately below.
+    // Read-only prevents the agent from modifying host application code
+    // (src/, dist/, package.json, etc.) which would bypass the sandbox
+    // entirely on next restart.
+    mounts.push({
+      hostPath: projectRoot,
+      containerPath: '/workspace/project',
+      readonly: true,
+    });
+
+    // Shadow .env so the agent cannot read secrets from the mounted project root.
+    // Credentials are injected by the OneCLI gateway, never exposed to containers.
+    const envFile = path.join(projectRoot, '.env');
+    if (fs.existsSync(envFile)) {
+      mounts.push({
+        hostPath: '/dev/null',
+        containerPath: '/workspace/project/.env',
+        readonly: true,
+      });
+    }
+
+    // Main also gets its group folder as the working directory
+    mounts.push({
+      hostPath: groupDir,
+      containerPath: '/workspace/group',
+      readonly: false,
+    });
+  } else {
+    // Other groups only get their own folder
+    mounts.push({
+      hostPath: groupDir,
+      containerPath: '/workspace/group',
+      readonly: false,
+    });
+
+    // Global memory directory (read-only for non-main)
+    // Only directory mounts are supported, not file mounts
+    const globalDir = path.join(GROUPS_DIR, 'global');
+    if (fs.existsSync(globalDir)) {
+      mounts.push({
+        hostPath: globalDir,
+        containerPath: '/workspace/global',
+        readonly: true,
+      });
+    }
+  }
+
+  // Per-group Claude sessions directory (isolated from other groups)
+  // Each group gets their own .claude/ to prevent cross-group session access
+  const groupSessionsDir = path.join(
+    DATA_DIR,
+    'sessions',
+    group.folder,
+    '.claude',
+  );
+  fs.mkdirSync(groupSessionsDir, { recursive: true });
+  const settingsFile = path.join(groupSessionsDir, 'settings.json');
+  if (!fs.existsSync(settingsFile)) {
+    fs.writeFileSync(
+      settingsFile,
+      JSON.stringify(
+        {
+          env: {
+            // Enable agent swarms (subagent orchestration)
+            // https://code.claude.com/docs/en/agent-teams#orchestrate-teams-of-claude-code-sessions
+            CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
+            // Load CLAUDE.md from additional mounted directories
+            // https://code.claude.com/docs/en/memory#load-memory-from-additional-directories
+            CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD: '1',
+            // Enable Claude's memory feature (persists user preferences between sessions)
+            // https://code.claude.com/docs/en/memory#manage-auto-memory
+            CLAUDE_CODE_DISABLE_AUTO_MEMORY: '0',
+          },
+        },
+        null,
+        2,
+      ) + '\n',
+    );
+  }
+
+  // Sync skills from container/skills/ into each group's .claude/skills/
+  // Only copy skills the agent is allowed to use (per agent-credentials.yaml allowlist).
+  // Also removes any previously-copied skills that are no longer allowed.
+  const skillsSrc = path.join(process.cwd(), 'container', 'skills');
+  const skillsDst = path.join(groupSessionsDir, 'skills');
+  if (fs.existsSync(skillsSrc)) {
+    const allowedSkills = getAgentSkills(group.folder);
+    // Remove disallowed skills that may have been copied in previous runs
+    if (allowedSkills !== null && fs.existsSync(skillsDst)) {
+      for (const existing of fs.readdirSync(skillsDst)) {
+        if (!allowedSkills.includes(existing)) {
+          fs.rmSync(path.join(skillsDst, existing), { recursive: true, force: true });
+        }
+      }
+    }
+    for (const skillDir of fs.readdirSync(skillsSrc)) {
+      const srcDir = path.join(skillsSrc, skillDir);
+      if (!fs.statSync(srcDir).isDirectory()) continue;
+      // If allowlist is defined, skip skills not in it
+      if (allowedSkills !== null && !allowedSkills.includes(skillDir)) continue;
+      const dstDir = path.join(skillsDst, skillDir);
+      fs.cpSync(srcDir, dstDir, { recursive: true });
+    }
+  }
+  mounts.push({
+    hostPath: groupSessionsDir,
+    containerPath: '/home/node/.claude',
+    readonly: false,
+  });
+
+  // Per-group IPC namespace: each group gets its own IPC directory
+  // This prevents cross-group privilege escalation via IPC
+  const groupIpcDir = resolveGroupIpcPath(group.folder);
+  fs.mkdirSync(path.join(groupIpcDir, 'messages'), { recursive: true });
+  fs.mkdirSync(path.join(groupIpcDir, 'tasks'), { recursive: true });
+  fs.mkdirSync(path.join(groupIpcDir, 'input'), { recursive: true });
+  mounts.push({
+    hostPath: groupIpcDir,
+    containerPath: '/workspace/ipc',
+    readonly: false,
+  });
+
+  // Copy agent-runner source into a per-group writable location so agents
+  // can customize it (add tools, change behavior) without affecting other
+  // groups. Recompiled on container startup via entrypoint.sh.
+  const agentRunnerSrc = path.join(
+    projectRoot,
+    'container',
+    'agent-runner',
+    'src',
+  );
+  const groupAgentRunnerDir = path.join(
+    DATA_DIR,
+    'sessions',
+    group.folder,
+    'agent-runner-src',
+  );
+  if (fs.existsSync(agentRunnerSrc)) {
+    const srcIndex = path.join(agentRunnerSrc, 'index.ts');
+    const cachedIndex = path.join(groupAgentRunnerDir, 'index.ts');
+    const needsCopy =
+      !fs.existsSync(groupAgentRunnerDir) ||
+      !fs.existsSync(cachedIndex) ||
+      (fs.existsSync(srcIndex) &&
+        fs.statSync(srcIndex).mtimeMs > fs.statSync(cachedIndex).mtimeMs);
+    if (needsCopy) {
+      fs.cpSync(agentRunnerSrc, groupAgentRunnerDir, { recursive: true });
+    }
+  }
+  mounts.push({
+    hostPath: groupAgentRunnerDir,
+    containerPath: '/app/src',
+    readonly: false,
+  });
+
+  // Additional mounts validated against external allowlist (tamper-proof from containers)
+  if (group.containerConfig?.additionalMounts) {
+    const validatedMounts = validateAdditionalMounts(
+      group.containerConfig.additionalMounts,
+      group.name,
+      isMain,
+    );
+
+    // Resolve worktree mounts: create per-group git worktrees so agents
+    // don't operate on the user's local checkout (branch switches, file
+    // edits stay isolated inside the worktree).
+    for (const mount of validatedMounts) {
+      if (mount.worktree && mount.originalHostPath) {
+        const containerPathName = mount.containerPath.replace(
+          '/workspace/extra/',
+          '',
+        );
+        try {
+          const worktreePath = await ensureWorktree(
+            mount.originalHostPath,
+            group.folder,
+            containerPathName,
+          );
+          mount.hostPath = worktreePath;
+          // Worktree mounts must be read-write so the agent can create branches and commit
+          mount.readonly = false;
+        } catch (err) {
+          logger.error(
+            { group: group.name, hostPath: mount.originalHostPath, err },
+            'Failed to create worktree, falling back to direct mount',
+          );
+        }
+      }
+    }
+
+    mounts.push(...validatedMounts);
+  }
+
+  // Per-agent tool mounting: build a filtered tools directory and mount it
+  // over /workspace/extra/tools to shadow the baked-in image tools.
+  // Only tools explicitly allowed in agent-credentials.yaml are accessible.
+  const allowedTools = getAgentTools(group.folder);
+  if (allowedTools !== null) {
+    const agentToolsDir = buildAgentToolsDir(group.folder, allowedTools);
+    mounts.push({
+      hostPath: agentToolsDir,
+      containerPath: '/workspace/extra/tools',
+      readonly: true,
+    });
+  }
+
+  return mounts;
+}
+
+async function buildContainerArgs(
+  mounts: VolumeMount[],
+  containerName: string,
+  agentIdentifier?: string,
+  senderEmail?: string,
+): Promise<string[]> {
+  const args: string[] = ['run', '-i', '--rm', '--name', containerName];
+
+  // Pass host timezone so container's local time matches the user's
+  args.push('-e', `TZ=${TIMEZONE}`);
+
+  // Forward service credentials from .env so Claude's Bash tool can call
+  // elastic_query.py, gh CLI, etc. inside the container.
+  const agentFolder = agentIdentifier || "global-claw";
+  const forwardedEnv = readEnvFile(getAgentEnvKeys(agentFolder));
+  for (const [key, value] of Object.entries(forwardedEnv)) {
+    args.push('-e', `${key}=${value}`);
+  }
+  // Generate a fresh GitHub App installation token if app credentials are configured.
+  // This ensures PRs are created as the Argus bot, not the user's personal account.
+  // Falls back to GITHUB_TOKEN from .env if app credentials are not set.
+  const needsGithub = getAgentEnvKeys(agentFolder).includes("GITHUB_TOKEN");
+  const githubToken = needsGithub ? await generateGitHubToken(forwardedEnv.GITHUB_TOKEN) : null;
+  if (needsGithub && !githubToken) {
+    // This agent requires GITHUB_TOKEN but generation failed. Proceeding without it
+    // would cause confusing auth failures deep into the run — fail fast instead.
+    throw new Error(`GitHub token generation failed for agent ${agentFolder} — check GITHUB_APP_ID, GITHUB_INSTALLATION_ID, and github-app.pem`);
+  }
+  if (githubToken) {
+    args.push('-e', `GITHUB_TOKEN=${githubToken}`);
+    args.push('-e', `GH_TOKEN=${githubToken}`);
+    // Force git to send auth on the first request. The OneCLI MITM proxy breaks
+    // git's normal 401-challenge-retry flow, so we inject the Authorization header
+    // upfront via git config env vars.
+    const gitAuthB64 = Buffer.from(`x-access-token:${githubToken}`).toString('base64');
+    args.push('-e', 'GIT_CONFIG_COUNT=1');
+    args.push('-e', 'GIT_CONFIG_KEY_0=http.extraHeader');
+    args.push('-e', `GIT_CONFIG_VALUE_0=Authorization: Basic ${gitAuthB64}`);
+  }
+
+
+  // Google access token — generated host-side from OAuth credentials in .env.
+  // Only injected for agents that have Google config keys (Drive folder IDs, etc.).
+  // The OAuth credentials themselves (CLIENT_SECRET, REFRESH_TOKEN) never enter the container.
+  const agentConfigKeys = getAgentEnvKeys(agentFolder);
+  const needsGoogle = agentConfigKeys.some(k => k.startsWith('GOOGLE_'));
+  if (needsGoogle) {
+    const googleToken = await generateGoogleAccessToken();
+    if (googleToken) {
+      args.push('-e', `GOOGLE_ACCESS_TOKEN=${googleToken}`);
+    } else {
+      logger.warn({ containerName }, 'Google OAuth not configured — GOOGLE_ACCESS_TOKEN not injected');
+    }
+  }
+
+  // OneCLI gateway handles credential injection — containers never see real secrets.
+  // The gateway intercepts HTTPS traffic and injects API keys or OAuth tokens.
+  const onecliApplied = await onecli.applyContainerConfig(args, {
+    addHostMapping: false, // Nanoclaw already handles host gateway
+    agent: agentIdentifier,
+  });
+  if (onecliApplied) {
+    logger.info({ containerName }, 'OneCLI gateway config applied');
+    // Python requests library needs its own CA bundle env var for OneCLI proxy TLS
+    args.push("-e", "REQUESTS_CA_BUNDLE=/tmp/onecli-combined-ca.pem");
+    args.push("-e", "GIT_SSL_CAINFO=/tmp/onecli-combined-ca.pem");
+  } else {
+    logger.warn(
+      { containerName },
+      'OneCLI gateway not reachable — container will have no credentials',
+    );
+  }
+
+  // Runtime-specific args for host gateway resolution
+  args.push(...hostGatewayArgs());
+
+  // Run as host user so bind-mounted files are accessible.
+  // Skip when running as root (uid 0), as the container's node user (uid 1000),
+  // or when getuid is unavailable (native Windows without WSL).
+  const hostUid = process.getuid?.();
+  const hostGid = process.getgid?.();
+  if (hostUid != null && hostUid !== 0 && hostUid !== 1000) {
+    args.push('--user', `${hostUid}:${hostGid}`);
+    args.push('-e', 'HOME=/home/node');
+  }
+
+  for (const mount of mounts) {
+    if (mount.readonly) {
+      args.push(...readonlyMountArgs(mount.hostPath, mount.containerPath));
+    } else {
+      args.push('-v', `${mount.hostPath}:${mount.containerPath}`);
+    }
+  }
+
+  // Inject sender email so agents can map the Slack user to external systems (e.g. Jira reporter).
+  // Must be before the image name — Docker treats args after the image as commands, not flags.
+  if (senderEmail) {
+    args.push('-e', `SLACK_USER_EMAIL=${senderEmail}`);
+  }
+
+  args.push(CONTAINER_IMAGE);
+
+  return args;
+}
+
+export async function runContainerAgent(
+  group: RegisteredGroup,
+  input: ContainerInput,
+  onProcess: (proc: ChildProcess, containerName: string) => void,
+  onOutput?: (output: ContainerOutput) => Promise<void>,
+): Promise<ContainerOutput> {
+  const startTime = Date.now();
+
+  const groupDir = resolveGroupFolderPath(group.folder);
+  fs.mkdirSync(groupDir, { recursive: true });
+
+  const mounts = await buildVolumeMounts(group, input.isMain);
+  const safeName = group.folder.replace(/[^a-zA-Z0-9-]/g, '-');
+  const containerName = `nanoclaw-${safeName}-${Date.now()}`;
+  // Main group uses the default OneCLI agent; others use their own agent.
+  const agentIdentifier = input.isMain
+    ? undefined
+    : group.folder.toLowerCase().replace(/_/g, '-');
+  const containerArgs = await buildContainerArgs(
+    mounts,
+    containerName,
+    agentIdentifier,
+    input.senderEmail,
+  );
+
+  logger.debug(
+    {
+      group: group.name,
+      containerName,
+      mounts: mounts.map(
+        (m) =>
+          `${m.hostPath} -> ${m.containerPath}${m.readonly ? ' (ro)' : ''}`,
+      ),
+      containerArgs: redactContainerArgs(containerArgs),
+    },
+    'Container mount configuration',
+  );
+
+  logger.info(
+    {
+      group: group.name,
+      containerName,
+      mountCount: mounts.length,
+      isMain: input.isMain,
+    },
+    'Spawning container agent',
+  );
+
+  const logsDir = path.join(groupDir, 'logs');
+  fs.mkdirSync(logsDir, { recursive: true });
+
+  return new Promise((resolve) => {
+    const container = spawn(CONTAINER_RUNTIME_BIN, containerArgs, {
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    onProcess(container, containerName);
+
+    // Apply iptables rules before writing to stdin — the container must not be
+    // able to make outbound calls before enforcement is in place.
+    // If enforcement fails for any reason, kill the container immediately.
+    const containerIp = getContainerIp(containerName);
+    if (!containerIp) {
+      logger.error({ containerName }, 'Could not get container IP — killing container');
+      container.kill();
+      resolve({ status: 'error', result: null, error: 'Could not get container IP for iptables enforcement' });
+      return;
+    }
+    try {
+      applyContainerIptables(containerName, containerIp);
+    } catch (err) {
+      const error = err instanceof Error ? err.message : String(err);
+      logger.error({ containerName, containerIp, error }, 'iptables enforcement failed — killing container');
+      container.kill();
+      resolve({ status: 'error', result: null, error: `iptables enforcement failed: ${error}` });
+      return;
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+
+    container.stdin.write(JSON.stringify(input));
+    container.stdin.end();
+
+    // Streaming output: parse OUTPUT_START/END marker pairs as they arrive
+    let parseBuffer = '';
+    let newSessionId: string | undefined;
+    let outputChain = Promise.resolve();
+
+    container.stdout.on('data', (data) => {
+      const chunk = data.toString();
+
+      // Always accumulate for logging
+      if (!stdoutTruncated) {
+        const remaining = CONTAINER_MAX_OUTPUT_SIZE - stdout.length;
+        if (chunk.length > remaining) {
+          stdout += chunk.slice(0, remaining);
+          stdoutTruncated = true;
+          logger.warn(
+            { group: group.name, size: stdout.length },
+            'Container stdout truncated due to size limit',
+          );
+        } else {
+          stdout += chunk;
+        }
+      }
+
+      // Stream-parse for output markers
+      if (onOutput) {
+        parseBuffer += chunk;
+        let startIdx: number;
+        while ((startIdx = parseBuffer.indexOf(OUTPUT_START_MARKER)) !== -1) {
+          const endIdx = parseBuffer.indexOf(OUTPUT_END_MARKER, startIdx);
+          if (endIdx === -1) break; // Incomplete pair, wait for more data
+
+          const jsonStr = parseBuffer
+            .slice(startIdx + OUTPUT_START_MARKER.length, endIdx)
+            .trim();
+          parseBuffer = parseBuffer.slice(endIdx + OUTPUT_END_MARKER.length);
+
+          try {
+            const parsed: ContainerOutput = JSON.parse(jsonStr);
+            if (parsed.newSessionId) {
+              newSessionId = parsed.newSessionId;
+            }
+            hadStreamingOutput = true;
+            // Activity detected — reset the hard timeout
+            resetTimeout();
+            // Call onOutput for all markers (including null results)
+            // so idle timers start even for "silent" query completions.
+            outputChain = outputChain.then(() => onOutput(parsed));
+          } catch (err) {
+            logger.warn(
+              { group: group.name, error: err },
+              'Failed to parse streamed output chunk',
+            );
+          }
+        }
+      }
+    });
+
+    container.stderr.on('data', (data) => {
+      const chunk = data.toString();
+      const lines = chunk.trim().split('\n');
+      for (const line of lines) {
+        if (line) logger.debug({ container: group.folder }, line);
+      }
+      // Don't reset timeout on stderr — SDK writes debug logs continuously.
+      // Timeout only resets on actual output (OUTPUT_MARKER in stdout).
+      if (stderrTruncated) return;
+      const remaining = CONTAINER_MAX_OUTPUT_SIZE - stderr.length;
+      if (chunk.length > remaining) {
+        stderr += chunk.slice(0, remaining);
+        stderrTruncated = true;
+        logger.warn(
+          { group: group.name, size: stderr.length },
+          'Container stderr truncated due to size limit',
+        );
+      } else {
+        stderr += chunk;
+      }
+    });
+
+    let timedOut = false;
+    let hadStreamingOutput = false;
+    const configTimeout = group.containerConfig?.timeout || CONTAINER_TIMEOUT;
+    // Grace period: hard timeout must be at least IDLE_TIMEOUT + 30s so the
+    // graceful _close sentinel has time to trigger before the hard kill fires.
+    const timeoutMs = Math.max(configTimeout, IDLE_TIMEOUT + 30_000);
+
+    const killOnTimeout = () => {
+      timedOut = true;
+      logger.error(
+        { group: group.name, containerName },
+        'Container timeout, stopping gracefully',
+      );
+      exec(stopContainer(containerName), { timeout: 15000 }, (err) => {
+        if (err) {
+          logger.warn(
+            { group: group.name, containerName, err },
+            'Graceful stop failed, force killing',
+          );
+          container.kill('SIGKILL');
+        }
+      });
+    };
+
+    let timeout = setTimeout(killOnTimeout, timeoutMs);
+
+    // Reset the timeout whenever there's activity (streaming output)
+    const resetTimeout = () => {
+      clearTimeout(timeout);
+      timeout = setTimeout(killOnTimeout, timeoutMs);
+    };
+
+    container.on('close', (code) => {
+      clearTimeout(timeout);
+      // Always clean up iptables rules, regardless of exit reason
+      cleanupContainerIptables(containerName);
+      const duration = Date.now() - startTime;
+
+      if (timedOut) {
+        const ts = new Date().toISOString().replace(/[:.]/g, '-');
+        const timeoutLog = path.join(logsDir, `container-${ts}.log`);
+        fs.writeFileSync(
+          timeoutLog,
+          [
+            `=== Container Run Log (TIMEOUT) ===`,
+            `Timestamp: ${new Date().toISOString()}`,
+            `Group: ${group.name}`,
+            `Container: ${containerName}`,
+            `Duration: ${duration}ms`,
+            `Exit Code: ${code}`,
+            `Had Streaming Output: ${hadStreamingOutput}`,
+          ].join('\n'),
+        );
+
+        // Timeout after output = idle cleanup, not failure.
+        // The agent already sent its response; this is just the
+        // container being reaped after the idle period expired.
+        if (hadStreamingOutput) {
+          logger.info(
+            { group: group.name, containerName, duration, code },
+            'Container timed out after output (idle cleanup)',
+          );
+          outputChain.then(() => {
+            resolve({
+              status: 'success',
+              result: null,
+              newSessionId,
+            });
+          });
+          return;
+        }
+
+        logger.error(
+          { group: group.name, containerName, duration, code },
+          'Container timed out with no output',
+        );
+
+        resolve({
+          status: 'error',
+          result: null,
+          error: `Container timed out after ${configTimeout}ms`,
+        });
+        return;
+      }
+
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const logFile = path.join(logsDir, `container-${timestamp}.log`);
+      const isVerbose =
+        process.env.LOG_LEVEL === 'debug' || process.env.LOG_LEVEL === 'trace';
+
+      const logLines = [
+        `=== Container Run Log ===`,
+        `Timestamp: ${new Date().toISOString()}`,
+        `Group: ${group.name}`,
+        `IsMain: ${input.isMain}`,
+        `Duration: ${duration}ms`,
+        `Exit Code: ${code}`,
+        `Stdout Truncated: ${stdoutTruncated}`,
+        `Stderr Truncated: ${stderrTruncated}`,
+        ``,
+      ];
+
+      const isError = code !== 0;
+
+      if (isVerbose || isError) {
+        // On error, log input metadata only — not the full prompt.
+        // Full input is only included at verbose level to avoid
+        // persisting user conversation content on every non-zero exit.
+        if (isVerbose) {
+          logLines.push(`=== Input ===`, JSON.stringify(input, null, 2), ``);
+        } else {
+          logLines.push(
+            `=== Input Summary ===`,
+            `Prompt length: ${input.prompt.length} chars`,
+            `Session ID: ${input.sessionId || 'new'}`,
+            ``,
+          );
+        }
+        logLines.push(
+          `=== Container Args ===`,
+          redactContainerArgs(containerArgs),
+          ``,
+          `=== Mounts ===`,
+          mounts
+            .map(
+              (m) =>
+                `${m.hostPath} -> ${m.containerPath}${m.readonly ? ' (ro)' : ''}`,
+            )
+            .join('\n'),
+          ``,
+          `=== Stderr${stderrTruncated ? ' (TRUNCATED)' : ''} ===`,
+          stderr,
+          ``,
+          `=== Stdout${stdoutTruncated ? ' (TRUNCATED)' : ''} ===`,
+          stdout,
+        );
+      } else {
+        logLines.push(
+          `=== Input Summary ===`,
+          `Prompt length: ${input.prompt.length} chars`,
+          `Session ID: ${input.sessionId || 'new'}`,
+          ``,
+          `=== Mounts ===`,
+          mounts
+            .map((m) => `${m.containerPath}${m.readonly ? ' (ro)' : ''}`)
+            .join('\n'),
+          ``,
+        );
+      }
+
+      fs.writeFileSync(logFile, logLines.join('\n'));
+      logger.debug({ logFile, verbose: isVerbose }, 'Container log written');
+
+      if (code !== 0) {
+        logger.error(
+          {
+            group: group.name,
+            code,
+            duration,
+            stderr,
+            stdout,
+            logFile,
+          },
+          'Container exited with error',
+        );
+
+        resolve({
+          status: 'error',
+          result: null,
+          error: `Container exited with code ${code}: ${stderr.slice(-200)}`,
+        });
+        return;
+      }
+
+      // Streaming mode: wait for output chain to settle, return completion marker
+      if (onOutput) {
+        outputChain.then(() => {
+          logger.info(
+            { group: group.name, duration, newSessionId },
+            'Container completed (streaming mode)',
+          );
+          resolve({
+            status: 'success',
+            result: null,
+            newSessionId,
+          });
+        });
+        return;
+      }
+
+      // Legacy mode: parse the last output marker pair from accumulated stdout
+      try {
+        // Extract JSON between sentinel markers for robust parsing
+        const startIdx = stdout.indexOf(OUTPUT_START_MARKER);
+        const endIdx = stdout.indexOf(OUTPUT_END_MARKER);
+
+        let jsonLine: string;
+        if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) {
+          jsonLine = stdout
+            .slice(startIdx + OUTPUT_START_MARKER.length, endIdx)
+            .trim();
+        } else {
+          // Fallback: last non-empty line (backwards compatibility)
+          const lines = stdout.trim().split('\n');
+          jsonLine = lines[lines.length - 1];
+        }
+
+        const output: ContainerOutput = JSON.parse(jsonLine);
+
+        logger.info(
+          {
+            group: group.name,
+            duration,
+            status: output.status,
+            hasResult: !!output.result,
+          },
+          'Container completed',
+        );
+
+        resolve(output);
+      } catch (err) {
+        logger.error(
+          {
+            group: group.name,
+            stdout,
+            stderr,
+            error: err,
+          },
+          'Failed to parse container output',
+        );
+
+        resolve({
+          status: 'error',
+          result: null,
+          error: `Failed to parse container output: ${err instanceof Error ? err.message : String(err)}`,
+        });
+      }
+    });
+
+    container.on('error', (err) => {
+      clearTimeout(timeout);
+      cleanupContainerIptables(containerName);
+      logger.error(
+        { group: group.name, containerName, error: err },
+        'Container spawn error',
+      );
+      resolve({
+        status: 'error',
+        result: null,
+        error: `Container spawn error: ${err.message}`,
+      });
+    });
+  });
+}
+
+export function writeTasksSnapshot(
+  groupFolder: string,
+  isMain: boolean,
+  tasks: Array<{
+    id: string;
+    groupFolder: string;
+    prompt: string;
+    script?: string | null;
+    schedule_type: string;
+    schedule_value: string;
+    status: string;
+    next_run: string | null;
+  }>,
+): void {
+  // Write filtered tasks to the group's IPC directory
+  const groupIpcDir = resolveGroupIpcPath(groupFolder);
+  fs.mkdirSync(groupIpcDir, { recursive: true });
+
+  // Main sees all tasks, others only see their own
+  const filteredTasks = isMain
+    ? tasks
+    : tasks.filter((t) => t.groupFolder === groupFolder);
+
+  const tasksFile = path.join(groupIpcDir, 'current_tasks.json');
+  fs.writeFileSync(tasksFile, JSON.stringify(filteredTasks, null, 2));
+}
+
+export interface AvailableGroup {
+  jid: string;
+  name: string;
+  lastActivity: string;
+  isRegistered: boolean;
+}
+
+/**
+ * Write available groups snapshot for the container to read.
+ * Only main group can see all available groups (for activation).
+ * Non-main groups only see their own registration status.
+ */
+export function writeGroupsSnapshot(
+  groupFolder: string,
+  isMain: boolean,
+  groups: AvailableGroup[],
+  _registeredJids: Set<string>,
+): void {
+  const groupIpcDir = resolveGroupIpcPath(groupFolder);
+  fs.mkdirSync(groupIpcDir, { recursive: true });
+
+  // Main sees all groups; others see nothing (they can't activate groups)
+  const visibleGroups = isMain ? groups : [];
+
+  const groupsFile = path.join(groupIpcDir, 'available_groups.json');
+  fs.writeFileSync(
+    groupsFile,
+    JSON.stringify(
+      {
+        groups: visibleGroups,
+        lastSync: new Date().toISOString(),
+      },
+      null,
+      2,
+    ),
+  );
+}