@fitlab-ai/agent-infra 0.7.6 → 0.8.0

package/lib/sandbox/commands/ls.ts

@@ -1,11 +1,8 @@
-import fs from 'node:fs';
-import path from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.ts';
 import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
-import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
 import { formatTable } from '../../table.ts';
 import { lookupShortIdByBranch } from '../../task/short-id.ts';
 import { fetchSandboxRows } from './list-running.ts';
@@ -20,7 +17,10 @@ id bound to each container's branch (via
 .agents/workspace/active/.short-ids.json), or '-' if no active task is
 bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
 A '-' means no active task is bound to that branch, so the sandbox is free
-to remove with "ai sandbox rm <branch>".`;
+to remove with "ai sandbox rm <branch>".
+
+Use "ai sandbox show <ref>" for a single sandbox's worktree and per-tool
+state paths.`;
 
 const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'BRANCH'] as const;
 
@@ -40,14 +40,6 @@ export function formatContainerTable(rows: ContainerTableRow[], zebra = false):
   );
 }
 
-function listChildren(dir: string): string[] {
-  if (!fs.existsSync(dir)) {
-    return [];
-  }
-
-  return fs.readdirSync(dir).sort().map((entry) => path.join(dir, entry));
-}
-
 export function ls(args: string[] = []): void {
   if (args.length > 0 && (args[0] === '--help' || args[0] === '-h')) {
     process.stdout.write(`${USAGE}\n`);
@@ -56,7 +48,6 @@ export function ls(args: string[] = []): void {
 
   const config = loadConfig();
   const engine = detectEngine(config);
-  const tools = resolveTools(config);
   const label = sandboxLabel(config);
   const { running, nonRunning } = fetchSandboxRows(engine, label, sandboxBranchLabel(config));
 
@@ -87,27 +78,4 @@ export function ls(args: string[] = []): void {
       );
     }
   }
-
-  p.log.step('Worktrees');
-  const worktrees = listChildren(config.worktreeBase);
-  if (worktrees.length === 0) {
-    p.log.warn('  No sandbox worktrees');
-  } else {
-    for (const worktree of worktrees) {
-      process.stdout.write(`  ${worktree}\n`);
-    }
-  }
-
-  for (const tool of tools) {
-    p.log.step(`${tool.name} state`);
-    const entries = toolProjectDirCandidates(tool, config.project)
-      .flatMap((dir) => listChildren(dir));
-    if (entries.length === 0) {
-      p.log.warn(`  No ${tool.name} sandbox state`);
-      continue;
-    }
-    for (const entry of entries) {
-      process.stdout.write(`  ${entry}\n`);
-    }
-  }
 }

package/lib/sandbox/commands/show.ts

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import type { SandboxConfig } from '../config.ts';
+import { loadConfig } from '../config.ts';
+import { assertValidBranchName, worktreeDirCandidates } from '../constants.ts';
+import { resolveBranchArg } from './list-running.ts';
+import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
+
+const USAGE = `Usage: ai sandbox show <branch | TASK-id | N | '#N'>
+
+Shows one sandbox's worktree path and per-tool state paths (Claude Code,
+Codex, Gemini CLI, OpenCode). The argument follows the same contract as
+'ai sandbox exec' and 'ai sandbox start': N (bare) is the recommended form
+for task short ids (e.g. 'ai sandbox show 11'); '#N', a TASK-id, or a plain
+branch name are also accepted. Use 'ai sandbox ls' for the container list.`;
+
+export type SandboxDetail = {
+  worktrees: string[];
+  toolStates: { name: string; entries: string[] }[];
+};
+
+function existingDirs(candidates: string[]): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const candidate of candidates) {
+    if (!seen.has(candidate) && fs.existsSync(candidate)) {
+      seen.add(candidate);
+      result.push(candidate);
+    }
+  }
+  return result;
+}
+
+export function collectSandboxDetail(config: SandboxConfig, branch: string): SandboxDetail {
+  const worktrees = existingDirs(worktreeDirCandidates(config, branch));
+  const toolStates = resolveTools(config).map((tool) => ({
+    name: tool.name,
+    entries: existingDirs(toolConfigDirCandidates(tool, config.project, branch))
+  }));
+  return { worktrees, toolStates };
+}
+
+export function show(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    if (args.length === 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const config = loadConfig();
+  const branch = resolveBranchArg(args[0]!, { repoRoot: config.repoRoot });
+  assertValidBranchName(branch);
+
+  const detail = collectSandboxDetail(config, branch);
+
+  p.intro(pc.cyan(`Sandbox detail for ${config.project} · ${branch}`));
+
+  p.log.step('Worktree');
+  if (detail.worktrees.length === 0) {
+    p.log.warn('  No worktree for this branch');
+  } else {
+    for (const worktree of detail.worktrees) {
+      process.stdout.write(`  ${worktree}\n`);
+    }
+  }
+
+  for (const tool of detail.toolStates) {
+    p.log.step(`${tool.name} state`);
+    if (tool.entries.length === 0) {
+      p.log.warn(`  No ${tool.name} sandbox state`);
+      continue;
+    }
+    for (const entry of tool.entries) {
+      process.stdout.write(`  ${entry}\n`);
+    }
+  }
+}

package/lib/sandbox/index.ts

@@ -9,6 +9,8 @@ Commands:
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
+  show <branch | TASK-id | N | '#N'>
+                               Show one sandbox's worktree and per-tool state paths
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
@@ -56,6 +58,11 @@ export async function runSandbox(args: string[]): Promise<void> {
       ls(rest);
       break;
     }
+    case 'show': {
+      const { show } = await import('./commands/show.ts');
+      show(rest);
+      break;
+    }
     case 'prune': {
       const { prune } = await import('./commands/prune.ts');
       await prune(rest);

package/lib/server/adapters/_contract.ts

@@ -0,0 +1,42 @@
+import type { ServerConfig } from '../config.ts';
+import type { Logger } from '../logger.ts';
+
+// Adapter contract for agent-infra-server.
+//
+// This is a pure type + constant module: it carries no runtime logic and no
+// third-party imports. Subtask B (the feishu adapter) and subtask C (the
+// command protocol / runner) build against these shapes. Bump
+// ADAPTER_CONTRACT_VERSION on a breaking change so plugin-loader can reject
+// adapters compiled against an older contract.
+export const ADAPTER_CONTRACT_VERSION = 1;
+
+// A normalized inbound message handed to the daemon command dispatcher.
+export type InboundMessage = {
+  adapter: string;
+  userId: string;
+  chatId: string;
+  text: string;
+  messageId: string;
+  raw: unknown;
+  reply: (text: string) => Promise<void>;
+};
+
+// Runtime context passed to every adapter's start(). dispatch() is registered
+// by the daemon; signal aborts when the daemon shuts down.
+export type AdapterCtx = {
+  config: ServerConfig;
+  logger: Logger;
+  dispatch: (message: InboundMessage) => Promise<void>;
+  signal: AbortSignal;
+};
+
+// The interface every adapter factory's default export must produce.
+export type Adapter = {
+  name: string;
+  start: (ctx: AdapterCtx) => Promise<void>;
+  stop: () => Promise<void>;
+  sendMessage: (target: { chatId: string }, text: string) => Promise<void>;
+};
+
+// The shape of an adapter module's default export (a factory).
+export type AdapterFactory = (adapterConfig: Record<string, unknown>) => Adapter;

package/lib/server/adapters/feishu/index.ts

@@ -0,0 +1,47 @@
+import type { Adapter, AdapterCtx, AdapterFactory, InboundMessage } from '../_contract.ts';
+import { createFeishuTransport, normalizeMessage } from './transport.ts';
+import type { FeishuTransport } from './transport.ts';
+
+// Assemble the feishu adapter. The transport is injectable so unit tests can
+// drive start/dispatch/reply/sendMessage against a fake transport without the
+// real SDK; production uses the default SDK-backed transport.
+export function createFeishuAdapter(
+  config: Record<string, unknown>,
+  transport: FeishuTransport = createFeishuTransport(config)
+): Adapter {
+  let ctx: AdapterCtx | null = null;
+
+  return {
+    name: 'feishu',
+    async start(adapterCtx) {
+      ctx = adapterCtx;
+      await transport.start(async (raw) => {
+        try {
+          const normalized = normalizeMessage(raw);
+          const message: InboundMessage = {
+            adapter: 'feishu',
+            userId: normalized.userId,
+            chatId: normalized.chatId,
+            text: normalized.text,
+            messageId: normalized.messageId,
+            raw: normalized.raw,
+            reply: (text) => transport.send(normalized.chatId, text)
+          };
+          await adapterCtx.dispatch(message);
+        } catch (error) {
+          ctx?.logger.err(`feishu: dropped message: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      });
+    },
+    async stop() {
+      await transport.stop();
+    },
+    async sendMessage(target, text) {
+      await transport.send(target.chatId, text);
+    }
+  };
+}
+
+const factory: AdapterFactory = (adapterConfig) => createFeishuAdapter(adapterConfig);
+
+export default factory;

package/lib/server/adapters/feishu/transport.ts

@@ -0,0 +1,128 @@
+import * as lark from '@larksuiteoapi/node-sdk';
+
+// Transport layer for the feishu adapter. All @larksuiteoapi/node-sdk surface is
+// confined here so the adapter body (index.ts) depends only on this narrow
+// interface plus the pure normalizeMessage(). That keeps normalize unit-testable
+// without the SDK and lets the adapter be assembled against a fake transport.
+
+export type FeishuTransport = {
+  // Begin receiving messages. onMessage is invoked with the raw SDK event for
+  // each inbound im.message.receive_v1.
+  start: (onMessage: (raw: unknown) => Promise<void>) => Promise<void>;
+  stop: () => Promise<void>;
+  send: (chatId: string, text: string) => Promise<void>;
+};
+
+export type NormalizedMessage = {
+  userId: string;
+  chatId: string;
+  text: string;
+  messageId: string;
+  raw: unknown;
+};
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? (value as Record<string, unknown>) : {};
+}
+
+// Strip feishu mention placeholders (e.g. "@_user_1") that the platform injects
+// for @-mentions, then collapse surrounding whitespace. A group message like
+// "@_user_1 /ping" normalizes to "/ping" so the daemon dispatcher matches it.
+function stripMentions(text: string): string {
+  return text.replace(/@_user_\d+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+// Parse an im.message.receive_v1 event into the daemon's shape. Pure: no SDK,
+// no IO. Throws on missing/invalid fields so the adapter can drop a single bad
+// message without crashing the long connection.
+export function normalizeMessage(event: unknown): NormalizedMessage {
+  const message = asRecord(asRecord(event).message);
+  const messageId = message.message_id;
+  const chatId = message.chat_id;
+  const content = message.content;
+  if (typeof messageId !== 'string' || typeof chatId !== 'string' || typeof content !== 'string') {
+    throw new Error('feishu: malformed im.message.receive_v1 event (missing message_id/chat_id/content)');
+  }
+
+  const senderId = asRecord(asRecord(asRecord(event).sender).sender_id);
+  const userId =
+    (typeof senderId.open_id === 'string' && senderId.open_id) ||
+    (typeof senderId.union_id === 'string' && senderId.union_id) ||
+    (typeof senderId.user_id === 'string' && senderId.user_id) ||
+    '';
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error('feishu: message.content is not valid JSON');
+  }
+  const rawText = asRecord(parsed).text;
+  if (typeof rawText !== 'string') {
+    throw new Error('feishu: unsupported message content (no text field)');
+  }
+
+  return { userId, chatId, text: stripMentions(rawText), messageId, raw: event };
+}
+
+function resolveDomain(value: unknown): number {
+  return value === 'lark' || value === 'Lark' ? lark.Domain.Lark : lark.Domain.Feishu;
+}
+
+// Build the real SDK-backed transport from adapter config. appId/appSecret come
+// from server config (appSecret only via server.local.json / env). The WSClient
+// long connection delivers events; the Client REST call sends replies.
+// Feishu self-built app IDs have this shape; the SDK's WSClient.start() silently
+// rejects anything else, so we validate up front to fail loudly instead.
+const APP_ID_PATTERN = /^cli_[0-9a-fA-F]{16}$/;
+
+export function createFeishuTransport(config: Record<string, unknown>): FeishuTransport {
+  const appId = String(config.appId ?? '').trim();
+  const appSecret = String(config.appSecret ?? '').trim();
+  const domain = resolveDomain(config.domain);
+
+  // Fail fast on missing or malformed credentials. The SDK only logs to its own
+  // logger and resolves WSClient.start() for an empty or malformed appId, so
+  // without these checks an enabled-but-misconfigured feishu adapter would be
+  // counted as loaded while the long connection never opens. Throwing here lets
+  // loadAdapters log `failed to load adapter "feishu": ...` and skip it.
+  if (appId === '' || appSecret === '') {
+    throw new Error(
+      'feishu: appId and appSecret are required; put appSecret in .agents/server.local.json or AGENT_INFRA_SERVER_adapters__feishu__appSecret'
+    );
+  }
+  if (!APP_ID_PATTERN.test(appId)) {
+    throw new Error('feishu: appId must match cli_[0-9a-fA-F]{16}');
+  }
+
+  const client = new lark.Client({ appId, appSecret, domain });
+  const wsClient = new lark.WSClient({ appId, appSecret, domain, loggerLevel: lark.LoggerLevel.warn });
+
+  return {
+    async start(onMessage) {
+      const eventDispatcher = new lark.EventDispatcher({}).register({
+        'im.message.receive_v1': async (data: unknown) => {
+          await onMessage(data);
+        }
+      });
+      wsClient.start({ eventDispatcher });
+    },
+    async stop() {
+      // Best-effort: close the long connection if the SDK exposes it. Never throw
+      // from shutdown — unloadAdapters isolates stop failures, but staying quiet
+      // keeps the daemon shutdown path clean.
+      const closable = wsClient as unknown as { close?: () => void };
+      try {
+        closable.close?.();
+      } catch {
+        // Ignore: the daemon is shutting down regardless.
+      }
+    },
+    async send(chatId, text) {
+      await client.im.message.create({
+        params: { receive_id_type: 'chat_id' },
+        data: { receive_id: chatId, msg_type: 'text', content: JSON.stringify({ text }) }
+      });
+    }
+  };
+}

package/lib/server/auth.ts

@@ -0,0 +1,28 @@
+export type CommandRole = 'read' | 'write' | 'exec';
+
+type AuthConfig = {
+  users?: unknown;
+};
+
+const ROLE_RANK: Record<CommandRole, number> = { read: 1, write: 2, exec: 3 };
+
+function userRole(auth: AuthConfig, key: string): CommandRole | null {
+  const users = auth.users;
+  if (!users || typeof users !== 'object' || Array.isArray(users)) return null;
+  const record = (users as Record<string, unknown>)[key];
+  if (!record || typeof record !== 'object' || Array.isArray(record)) return null;
+  const role = (record as Record<string, unknown>).role;
+  return role === 'read' || role === 'write' || role === 'exec' ? role : null;
+}
+
+export function authorize(
+  user: { adapter: string; userId: string },
+  required: CommandRole,
+  auth: AuthConfig | undefined
+): { ok: true } | { ok: false; message: string } {
+  const role = userRole(auth ?? {}, `${user.adapter}:${user.userId}`);
+  if (!role || ROLE_RANK[role] < ROLE_RANK[required]) {
+    return { ok: false, message: `requires ${required}` };
+  }
+  return { ok: true };
+}

package/lib/server/config.ts

@@ -0,0 +1,228 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+export type ServerLogConfig = {
+  path: string;
+  rotateAtBytes: number;
+};
+
+export type ServerAdapterConfig = {
+  enabled: boolean;
+  [key: string]: unknown;
+};
+
+export type ServerConfig = {
+  repoRoot: string;
+  log: ServerLogConfig;
+  // Absolute path to the PID file, under ~/.agent-infra/run/<project>/server.pid.
+  pidFile: string;
+  heartbeatMs: number;
+  adapters: Record<string, ServerAdapterConfig>;
+  command?: Record<string, unknown>;
+  auth?: Record<string, unknown>;
+  stream?: Record<string, unknown>;
+};
+
+export type ServerValidation =
+  | { ok: true }
+  | { ok: false; error: string; fields: string[] };
+
+const ENV_PREFIX = 'AGENT_INFRA_SERVER_';
+
+// Keys whose presence in the *committed* server.json is treated as a leaked
+// secret. Secrets belong in .agents/server.local.json or the environment.
+const SECRET_KEY_PATTERN = /secret|token|password|passwd|credential|apikey|api_key/i;
+
+const DEFAULT_ROTATE_BYTES = 52_428_800; // 50 MiB
+
+export const DEFAULT_SERVER_CONFIG: {
+  log: { rotateAtBytes: number };
+  heartbeatMs: number;
+  adapters: Record<string, ServerAdapterConfig>;
+} = {
+  log: { rotateAtBytes: DEFAULT_ROTATE_BYTES },
+  heartbeatMs: 30_000,
+  adapters: {}
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+// Daemon runtime state (log + PID) lives OUTSIDE the repo, under the user's home
+// directory, keyed by the .airc.json "project" AND a stable hash of the repo
+// root path:
+//   ~/.agent-infra/logs/<project>/<repo-hash>/server.log
+//   ~/.agent-infra/run/<project>/<repo-hash>/server.pid
+// The <project> segment groups a project's checkouts for readability; the
+// <repo-hash> segment guarantees that two checkouts/worktrees of the same
+// project (same "project" but different absolute path) get ISOLATED runtime
+// dirs, so they never read/control each other's daemon. Using os.homedir() +
+// path.join keeps this correct on Windows too (C:\Users\<name>\.agent-infra\...).
+// An explicit log.path in server.json/.local/env still overrides the log default.
+function resolveProjectKey(repoRoot: string): string {
+  try {
+    const airc = JSON.parse(
+      fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')
+    ) as { project?: unknown };
+    if (typeof airc.project === 'string' && airc.project.trim() !== '') {
+      return airc.project.trim();
+    }
+  } catch {
+    // No .airc.json / unreadable → fall back to the repo directory name.
+  }
+  return path.basename(repoRoot);
+}
+
+// Short, stable, filesystem-safe discriminator for a checkout's absolute path.
+function repoKey(repoRoot: string): string {
+  return createHash('sha256').update(repoRoot).digest('hex').slice(0, 12);
+}
+
+function runtimePath(repoRoot: string, projectKey: string, kind: 'logs' | 'run', file: string): string {
+  return path.join(homedir(), '.agent-infra', kind, projectKey, repoKey(repoRoot), file);
+}
+
+function detectRepoRoot(): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    throw new Error('server: current directory is not inside a git repository');
+  }
+}
+
+// Plain-object deep merge: objects recurse, everything else (arrays, scalars)
+// replaces. Intentionally small — server config is shallow and this avoids
+// coupling to lib/merge.ts, whose semantics target the task workspace.
+function deepMerge<T extends Record<string, unknown>>(base: T, override: Record<string, unknown>): T {
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    const current = result[key];
+    if (isPlainObject(current) && isPlainObject(value)) {
+      result[key] = deepMerge(current, value);
+    } else {
+      result[key] = value;
+    }
+  }
+  return result as T;
+}
+
+function readJsonIfPresent(filePath: string): Record<string, unknown> {
+  if (!fs.existsSync(filePath)) return {};
+  const parsed: unknown = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  if (!isPlainObject(parsed)) {
+    throw new Error(`server: ${path.basename(filePath)} must contain a JSON object`);
+  }
+  return parsed;
+}
+
+function coerceEnvValue(raw: string): unknown {
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw !== '' && !Number.isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+// Map AGENT_INFRA_SERVER_<path> env vars into a nested override object. The
+// path after the prefix uses `__` to separate nesting levels and is treated
+// case-sensitively (e.g. AGENT_INFRA_SERVER_adapters__dev__enabled=false ->
+// { adapters: { dev: { enabled: false } } }).
+function envOverrides(env: NodeJS.ProcessEnv): Record<string, unknown> {
+  const override: Record<string, unknown> = {};
+  for (const [key, rawValue] of Object.entries(env)) {
+    if (!key.startsWith(ENV_PREFIX) || rawValue === undefined) continue;
+    const segments = key.slice(ENV_PREFIX.length).split('__').filter(Boolean);
+    if (segments.length === 0) continue;
+    let cursor = override;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+      const segment = segments[i] as string;
+      const next = cursor[segment];
+      if (!isPlainObject(next)) {
+        cursor[segment] = {};
+      }
+      cursor = cursor[segment] as Record<string, unknown>;
+    }
+    cursor[segments[segments.length - 1] as string] = coerceEnvValue(rawValue);
+  }
+  return override;
+}
+
+// Collect dotted paths of secret-looking, non-empty string fields.
+function collectSecretFields(value: unknown, trail: string[] = []): string[] {
+  if (!isPlainObject(value)) return [];
+  const found: string[] = [];
+  for (const [key, child] of Object.entries(value)) {
+    const here = [...trail, key];
+    if (SECRET_KEY_PATTERN.test(key) && typeof child === 'string' && child.trim() !== '') {
+      found.push(here.join('.'));
+    } else if (isPlainObject(child)) {
+      found.push(...collectSecretFields(child, here));
+    }
+  }
+  return found;
+}
+
+// Reject secrets that live in the committed server.json. server.local.json and
+// the environment are the sanctioned places for secrets and are not scanned.
+export function validateServerConfig(committed: Record<string, unknown>): ServerValidation {
+  const fields = collectSecretFields(committed);
+  if (fields.length > 0) {
+    return {
+      ok: false,
+      fields,
+      error:
+        `server: refusing to start — secret-like field(s) found in committed .agents/server.json: ${fields.join(', ')}. ` +
+        'Move them to .agents/server.local.json or AGENT_INFRA_SERVER_* environment variables.'
+    };
+  }
+  return { ok: true };
+}
+
+export function loadServerConfig({ rootDir }: { rootDir?: string } = {}): ServerConfig {
+  const repoRoot = rootDir ?? detectRepoRoot();
+  const agentsDir = path.join(repoRoot, '.agents');
+
+  const committed = readJsonIfPresent(path.join(agentsDir, 'server.json'));
+  const validation = validateServerConfig(committed);
+  if (!validation.ok) {
+    throw new Error(validation.error);
+  }
+  const local = readJsonIfPresent(path.join(agentsDir, 'server.local.json'));
+
+  let merged: Record<string, unknown> = deepMerge<Record<string, unknown>>(
+    { log: { rotateAtBytes: DEFAULT_ROTATE_BYTES }, heartbeatMs: DEFAULT_SERVER_CONFIG.heartbeatMs, adapters: {} },
+    committed
+  );
+  merged = deepMerge(merged, local);
+  merged = deepMerge(merged, envOverrides(process.env));
+
+  const projectKey = resolveProjectKey(repoRoot);
+
+  const log = isPlainObject(merged.log) ? merged.log : {};
+  // No explicit log.path → default under ~/.agent-infra/logs/<project>/.
+  // Explicit relative path resolves against the repo root; absolute is used as-is.
+  const explicitPath = typeof log.path === 'string' ? log.path : null;
+  const resolvedLogPath = explicitPath === null
+    ? runtimePath(repoRoot, projectKey, 'logs', 'server.log')
+    : (path.isAbsolute(explicitPath) ? explicitPath : path.join(repoRoot, explicitPath));
+
+  return {
+    repoRoot,
+    pidFile: runtimePath(repoRoot, projectKey, 'run', 'server.pid'),
+    log: {
+      path: resolvedLogPath,
+      rotateAtBytes: typeof log.rotateAtBytes === 'number' ? log.rotateAtBytes : DEFAULT_ROTATE_BYTES
+    },
+    heartbeatMs: typeof merged.heartbeatMs === 'number' ? merged.heartbeatMs : DEFAULT_SERVER_CONFIG.heartbeatMs,
+    adapters: isPlainObject(merged.adapters) ? (merged.adapters as Record<string, ServerAdapterConfig>) : {},
+    command: isPlainObject(merged.command) ? merged.command : undefined,
+    auth: isPlainObject(merged.auth) ? merged.auth : undefined,
+    stream: isPlainObject(merged.stream) ? merged.stream : undefined
+  };
+}