@fitlab-ai/agent-infra 0.5.0 → 0.5.2

package/README.md

@@ -35,6 +35,20 @@ agent-infra standardizes that collaboration surface. It gives every supported AI
 
 ## See it in Action
 
+### Install & Initialize
+
+<p align="center">
+  <img src="./assets/demo-init.gif" alt="CLI install and initialize demo" width="100%" style="max-width: 720px;">
+</p>
+
+Once initialized, open the project in your AI TUI and install the latest skills:
+
+```bash
+/update-agent-infra
+```
+
+> AI reads `.agents/.airc.json`, auto-locates the installed template root, and syncs the latest skill manifests, managed files, and registry deterministically via `sync-templates.js`.
+
 **Scenario**: Issue #42 reports *"Login API returns 500 when email contains a plus sign"*. Here is the full fix lifecycle — AI does the heavy lifting, you stay in control:
 
 ```bash
@@ -181,10 +195,12 @@ This detects the packaged template version and renders all managed files. The sa
 
 ### Sandbox aliases and GitHub CLI
 
-`ai sandbox create` now bootstraps the host-side aliases file at `~/.ai-sandbox-aliases` on first run. The generated file includes ready-to-edit yolo shortcuts for Claude, Codex, Gemini CLI, and OpenCode, and every sandbox syncs that file into `/home/devuser/.bash_aliases`.
+`ai sandbox create` now bootstraps the host-side aliases file at `~/.agent-infra/aliases/sandbox.sh` on first run. The generated file includes ready-to-edit yolo shortcuts for Claude, Codex, Gemini CLI, and OpenCode, and every sandbox syncs that file into `/home/devuser/.bash_aliases`.
 
 The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the host, `ai sandbox create` injects the token into the container as `GH_TOKEN`, so `gh` commands work inside the sandbox without extra setup.
 
+`ai sandbox exec` also forwards a small terminal-detection whitelist (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LC_TERMINAL`, `LC_TERMINAL_VERSION`) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.
+
 <a id="architecture-overview"></a>
 
 ## Architecture Overview
@@ -394,7 +410,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.0",
+  "templateVersion": "v0.5.2",
   "files": {
     "managed": [
       ".agents/workspace/README.md",

package/README.zh-CN.md

@@ -35,6 +35,20 @@ agent-infra 的目标就是把这层协作面标准化。它为所有支持的 A
 
 ## 实战演示
 
+### 安装与初始化
+
+<p align="center">
+  <img src="./assets/demo-init.gif" alt="CLI 安装初始化演示" width="100%" style="max-width: 720px;">
+</p>
+
+完成初始化后，在你的 AI TUI 中打开项目并安装最新 skills：
+
+```bash
+/update-agent-infra
+```
+
+> AI 读取 `.agents/.airc.json`，自动定位已安装的模板根目录，并通过 `sync-templates.js` 确定性地同步最新的 skill 清单、managed 文件和注册表。
+
 **场景**：Issue #42 报告 *"登录接口在邮箱包含加号时返回 500"*。以下是完整的修复流程 —— AI 执行主要工作，你掌控方向：
 
 ```bash
@@ -181,10 +195,12 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 ### 沙箱 aliases 与 GitHub CLI
 
-`ai sandbox create` 在首次运行时会自动生成宿主机侧的 `~/.ai-sandbox-aliases`。该文件内置了 Claude、Codex、Gemini CLI 和 OpenCode 的 yolo 快捷命令模板，你可以直接修改；每次创建沙箱时，这个文件都会同步到容器内的 `/home/devuser/.bash_aliases`。
+`ai sandbox create` 在首次运行时会自动生成宿主机侧的 `~/.agent-infra/aliases/sandbox.sh`。该文件内置了 Claude、Codex、Gemini CLI 和 OpenCode 的 yolo 快捷命令模板，你可以直接修改；每次创建沙箱时，这个文件都会同步到容器内的 `/home/devuser/.bash_aliases`。
 
 沙箱镜像也会预装 `gh`。如果宿主机上的 `gh auth token` 能成功返回 token，`ai sandbox create` 会把它以 `GH_TOKEN` 环境变量注入容器，让你在沙箱里直接使用 `gh`，无需额外登录配置。
 
+`ai sandbox exec` 也会向容器透传一小组终端检测白名单变量（`TERM_PROGRAM`、`TERM_PROGRAM_VERSION`、`LC_TERMINAL`、`LC_TERMINAL_VERSION`）。这样可以让交互式 TUI 保持与宿主终端一致的行为，例如 Claude Code 的 `Shift+Enter` 换行支持，同时避免把整个宿主环境灌入容器。
+
 <a id="architecture-overview"></a>
 
 ## 架构概览
@@ -394,7 +410,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.0",
+  "templateVersion": "v0.5.2",
   "files": {
     "managed": [
       ".agents/workspace/README.md",

package/bin/cli.js

@@ -14,7 +14,7 @@ const USAGE = `agent-infra - bootstrap AI collaboration infrastructure
 
 Usage:
   agent-infra init        Initialize a new project with update-agent-infra seed command
-  agent-infra merge       Merge archived tasks from another archive directory
+  agent-infra merge       Merge tasks from another workspace directory (active/blocked/completed/archive)
   agent-infra update      Update seed files and sync file registry for an existing project
   agent-infra sandbox     Manage Docker-based AI sandboxes
   agent-infra version     Show version

package/lib/defaults.json

@@ -1,4 +1,7 @@
 {
+  "platform": {
+    "type": "github"
+  },
   "sandbox": {
     "runtimes": [
       "node20"

package/lib/init.js

@@ -92,14 +92,22 @@ async function cmdInit() {
   }
 
   let language = await prompt('Language (en / zh)', 'zh');
-  closePrompt();
   if (language === 'zh') language = 'zh-CN';
   if (language !== 'en' && language !== 'zh-CN') {
+    closePrompt();
     err(`Language must be 'en' or 'zh'. Got: ${language}`);
     process.exitCode = 1;
     return;
   }
 
+  const platformType = (await prompt('Platform type', 'github')).trim() || 'github';
+  closePrompt();
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(platformType)) {
+    err(`Platform type must match /^[a-z0-9][a-z0-9-]*$/. Got: ${platformType}`);
+    process.exitCode = 1;
+    return;
+  }
+
   const project = projectName;
   const replacements = { project, org: orgName };
 
@@ -118,9 +126,9 @@ async function cmdInit() {
     geminiSrc = 'update-agent-infra.zh-CN.toml';
     opencodeSrc = 'update-agent-infra.zh-CN.md';
   } else {
-    claudeSrc = 'update-agent-infra.md';
-    geminiSrc = 'update-agent-infra.toml';
-    opencodeSrc = 'update-agent-infra.md';
+    claudeSrc = 'update-agent-infra.en.md';
+    geminiSrc = 'update-agent-infra.en.toml';
+    opencodeSrc = 'update-agent-infra.en.md';
   }
 
   // install skill
@@ -128,7 +136,8 @@ async function cmdInit() {
     path.join(templateDir, '.agents', 'skills', 'update-agent-infra'),
     path.join('.agents', 'skills', 'update-agent-infra'),
     replacements,
-    language
+    language,
+    platformType
   );
   ok('Installed .agents/skills/update-agent-infra/');
 
@@ -161,6 +170,7 @@ async function cmdInit() {
     project: projectName,
     org: orgName,
     language,
+    platform: { type: platformType },
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
     labels: structuredClone(defaults.labels),

package/lib/merge.js

@@ -6,6 +6,15 @@ const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
 const TITLE_RE = /^# (.+)$/m;
 const DATE_FROM_PATH_RE = /(?:^|[/\\])(\d{4})[/\\](\d{2})[/\\](\d{2})(?:[/\\]|$)/;
+const MUTABLE_SECTIONS = ['active', 'blocked', 'completed'];
+const ALL_SECTIONS = [...MUTABLE_SECTIONS, 'archive'];
+const SECTION_LABELS = {
+  active: 'Active',
+  blocked: 'Blocked',
+  completed: 'Completed',
+  archive: 'Archive'
+};
+const DIVIDER = '═'.repeat(55);
 
 function extractField(content, fieldName) {
   const match = content.match(FRONTMATTER_RE);
@@ -394,50 +403,305 @@ function removeManifestFiles(rootDir) {
   }
 }
 
-async function cmdMerge(args) {
-  const sourcePath = args[0];
-  if (!sourcePath) {
-    throw new Error('Usage: agent-infra merge <source-path>');
+function formatTimestamp(date) {
+  return [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0')
+  ].join('-') + ' ' + [
+    String(date.getHours()).padStart(2, '0'),
+    String(date.getMinutes()).padStart(2, '0'),
+    String(date.getSeconds()).padStart(2, '0')
+  ].join(':');
+}
+
+function formatBackupTimestamp(date) {
+  return [
+    date.getFullYear(),
+    String(date.getMonth() + 1).padStart(2, '0'),
+    String(date.getDate()).padStart(2, '0')
+  ].join('') + `-${String(date.getHours()).padStart(2, '0')}${String(date.getMinutes()).padStart(2, '0')}${String(date.getSeconds()).padStart(2, '0')}`;
+}
+
+function toPosixPath(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+function getLatestFileMtime(taskDir) {
+  let latestMs = null;
+  const stack = [taskDir];
+
+  while (stack.length > 0) {
+    const currentDir = stack.pop();
+    if (!currentDir || !fs.existsSync(currentDir)) {
+      continue;
+    }
+
+    for (const entry of fs.readdirSync(currentDir, { withFileTypes: true })) {
+      const entryPath = path.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+        continue;
+      }
+
+      const { mtimeMs } = fs.statSync(entryPath);
+      latestMs = latestMs === null ? mtimeMs : Math.max(latestMs, mtimeMs);
+    }
   }
 
-  const resolvedSource = path.resolve(sourcePath);
-  if (!fs.existsSync(resolvedSource)) {
-    throw new Error(`Source path does not exist: ${sourcePath}`);
+  return latestMs;
+}
+
+function getTaskTimestamp(taskDir) {
+  const taskFile = path.join(taskDir, 'task.md');
+
+  if (fs.existsSync(taskFile)) {
+    const content = fs.readFileSync(taskFile, 'utf8');
+    const updatedAt = extractField(content, 'updated_at');
+    if (updatedAt) {
+      return { value: updatedAt, source: 'frontmatter' };
+    }
+
+    const taskFileStat = fs.statSync(taskFile);
+    return {
+      value: formatTimestamp(taskFileStat.mtime),
+      source: 'task-mtime'
+    };
   }
 
-  if (!fs.statSync(resolvedSource).isDirectory()) {
-    throw new Error(`Source path is not a directory: ${sourcePath}`);
+  const latestMs = getLatestFileMtime(taskDir);
+  if (latestMs !== null) {
+    return {
+      value: formatTimestamp(new Date(latestMs)),
+      source: 'dir-mtime'
+    };
+  }
+
+  const dirStat = fs.statSync(taskDir);
+  return {
+    value: formatTimestamp(dirStat.mtime),
+    source: 'dir-mtime'
+  };
+}
+
+function compareTimestamps(left, right) {
+  return left.value.localeCompare(right.value);
+}
+
+function scanWorkspaceSection(rootDir, sectionName) {
+  const sectionDir = path.join(rootDir, sectionName);
+  if (!fs.existsSync(sectionDir) || !fs.statSync(sectionDir).isDirectory()) {
+    return [];
   }
 
-  const archiveDir = path.join(process.cwd(), '.agents', 'workspace', 'archive');
-  const sourceTasks = scanSourceTasks(resolvedSource);
-  const merged = [];
-  const skipped = [];
+  const records = [];
+  for (const entry of fs.readdirSync(sectionDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !TASK_ID_RE.test(entry.name)) {
+      continue;
+    }
 
-  fs.mkdirSync(archiveDir, { recursive: true });
+    const taskDir = path.join(sectionDir, entry.name);
+    const taskFile = path.join(taskDir, 'task.md');
+    if (!fs.existsSync(taskFile)) {
+      continue;
+    }
+
+    records.push({
+      taskId: entry.name,
+      section: sectionName,
+      taskDir,
+      timestamp: getTaskTimestamp(taskDir)
+    });
+  }
+
+  return records.sort((left, right) => left.taskId.localeCompare(right.taskId));
+}
+
+function buildWorkspaceIndex(workspaceDir) {
+  const index = new Map();
+
+  for (const section of MUTABLE_SECTIONS) {
+    for (const record of scanWorkspaceSection(workspaceDir, section)) {
+      index.set(record.taskId, record);
+    }
+  }
+
+  return index;
+}
+
+function backupTaskDir(backupRoot, section, taskDir, taskId) {
+  const backupDir = path.join(backupRoot, section, taskId);
+  fs.mkdirSync(path.dirname(backupDir), { recursive: true });
+  fs.cpSync(taskDir, backupDir, { recursive: true });
+  return backupDir;
+}
+
+function copyTaskToSection(sourceTask, workspaceDir) {
+  const destinationDir = path.join(workspaceDir, sourceTask.section, sourceTask.taskId);
+  fs.mkdirSync(path.dirname(destinationDir), { recursive: true });
+  fs.cpSync(sourceTask.taskDir, destinationDir, { recursive: true });
+  return destinationDir;
+}
+
+function detectSourceMode(sourcePath) {
+  for (const section of ALL_SECTIONS) {
+    const sectionDir = path.join(sourcePath, section);
+    if (fs.existsSync(sectionDir) && fs.statSync(sectionDir).isDirectory()) {
+      return 'workspace';
+    }
+  }
+
+  return 'legacy-archive';
+}
+
+function createReport(sourcePath, backupRoot) {
+  return {
+    sourcePath,
+    backupRoot,
+    sections: {
+      active: { copied: [], updated: [], moved: [], skipped: [] },
+      blocked: { copied: [], updated: [], moved: [], skipped: [] },
+      completed: { copied: [], updated: [], moved: [], skipped: [] },
+      archive: { copied: [], skipped: [] }
+    },
+    details: [],
+    backupCount: 0
+  };
+}
+
+function recordMutable(report, reportSection, action, entry) {
+  report.sections[reportSection][action].push(entry);
+  report.details.push(entry);
+}
+
+function recordArchive(report, action, entry) {
+  report.sections.archive[action].push(entry);
+  report.details.push(entry);
+}
+
+function mergeMutableSections({ sourceWorkspace, localWorkspace, backupRoot, report }) {
+  const localIndex = buildWorkspaceIndex(localWorkspace);
+
+  for (const sourceSection of MUTABLE_SECTIONS) {
+    const sourceTasks = scanWorkspaceSection(sourceWorkspace, sourceSection);
+
+    for (const sourceTask of sourceTasks) {
+      const localMatch = localIndex.get(sourceTask.taskId) || null;
+
+      if (!localMatch) {
+        const destinationDir = copyTaskToSection(sourceTask, localWorkspace);
+        localIndex.set(sourceTask.taskId, {
+          taskId: sourceTask.taskId,
+          section: sourceTask.section,
+          taskDir: destinationDir,
+          timestamp: getTaskTimestamp(destinationDir)
+        });
+        recordMutable(report, sourceTask.section, 'copied', {
+          action: 'copied',
+          symbol: '✓',
+          taskId: sourceTask.taskId,
+          section: sourceTask.section,
+          detail: 'copied'
+        });
+        continue;
+      }
+
+      const comparison = compareTimestamps(sourceTask.timestamp, localMatch.timestamp);
+      if (comparison > 0) {
+        backupTaskDir(backupRoot, localMatch.section, localMatch.taskDir, localMatch.taskId);
+        report.backupCount += 1;
+        fs.rmSync(localMatch.taskDir, { recursive: true, force: true });
+
+        const destinationDir = copyTaskToSection(sourceTask, localWorkspace);
+        localIndex.set(sourceTask.taskId, {
+          taskId: sourceTask.taskId,
+          section: sourceTask.section,
+          taskDir: destinationDir,
+          timestamp: getTaskTimestamp(destinationDir)
+        });
+
+        if (localMatch.section === sourceTask.section) {
+          recordMutable(report, sourceTask.section, 'updated', {
+            action: 'updated',
+            symbol: '↑',
+            taskId: sourceTask.taskId,
+            section: sourceTask.section,
+            detail: `updated (source newer: ${sourceTask.timestamp.value} > ${localMatch.timestamp.value})`
+          });
+        } else {
+          recordMutable(report, localMatch.section, 'moved', {
+            action: 'moved',
+            symbol: '⇄',
+            taskId: sourceTask.taskId,
+            fromSection: localMatch.section,
+            toSection: sourceTask.section,
+            detail: `moved (source newer: ${sourceTask.timestamp.value} > ${localMatch.timestamp.value})`
+          });
+        }
+
+        continue;
+      }
+
+      if (comparison < 0) {
+        recordMutable(report, localMatch.section, 'skipped', {
+          action: 'skipped',
+          symbol: '⊘',
+          taskId: sourceTask.taskId,
+          section: localMatch.section,
+          detail: `skipped (local newer: ${localMatch.timestamp.value} > ${sourceTask.timestamp.value})`
+        });
+        continue;
+      }
+
+      recordMutable(report, localMatch.section, 'skipped', {
+        action: 'skipped',
+        symbol: '⊘',
+        taskId: sourceTask.taskId,
+        section: localMatch.section,
+        detail: `skipped (same timestamp: ${sourceTask.timestamp.value})`
+      });
+    }
+  }
+}
+
+function mergeArchiveSection(sourceArchive, localArchive, report) {
+  const sourceTasks = scanSourceTasks(sourceArchive);
 
   for (const task of sourceTasks) {
-    const existingTaskDir = taskExistsInArchive(archiveDir, task.taskId);
+    const existingTaskDir = taskExistsInArchive(localArchive, task.taskId);
     if (existingTaskDir) {
-      skipped.push({
+      recordArchive(report, 'skipped', {
+        action: 'skipped',
+        symbol: '⊘',
         taskId: task.taskId,
-        relativePath: path.relative(archiveDir, existingTaskDir).split(path.sep).join('/') + '/'
+        section: 'archive',
+        relativePath: `${toPosixPath(path.relative(localArchive, existingTaskDir))}/`,
+        detail: `skipped (already exists at ${toPosixPath(path.relative(localArchive, existingTaskDir))}/)`
       });
       continue;
     }
 
-    const destinationDir = path.join(archiveDir, task.relativePath);
+    const destinationDir = path.join(localArchive, task.relativePath);
     fs.mkdirSync(path.dirname(destinationDir), { recursive: true });
     fs.cpSync(task.taskDir, destinationDir, { recursive: true });
-    merged.push({
+    recordArchive(report, 'copied', {
+      action: 'copied',
+      symbol: '✓',
       taskId: task.taskId,
-      relativePath: task.relativePath
+      section: 'archive',
+      relativePath: task.relativePath,
+      detail: 'copied'
     });
   }
 
-  rebuildManifests(archiveDir);
+  return sourceTasks.length;
+}
+
+function printLegacyArchiveMessages(report, sourcePath) {
+  const merged = report.sections.archive.copied;
+  const skipped = report.sections.archive.skipped;
 
-  if (sourceTasks.length === 0) {
+  if (merged.length === 0 && skipped.length === 0) {
     info(`No archived tasks found in ${sourcePath}`);
   }
 
@@ -453,13 +717,169 @@ async function cmdMerge(args) {
   info('Merge summary');
   info(`- Merged: ${merged.length}`);
   info(`- Skipped: ${skipped.length}`);
+  process.stdout.write('\n');
+}
+
+function printSection(lines, name, counts) {
+  const title = `${SECTION_LABELS[name].padEnd(9, ' ')} (.agents/workspace/${name}/):`;
+  lines.push(title);
+
+  const entries = [
+    ['copied', '✓ Copied  '],
+    ['updated', '↑ Updated '],
+    ['moved', '⇄ Moved   '],
+    ['skipped', '⊘ Skipped ']
+  ].filter(([key]) => Array.isArray(counts[key]));
+
+  const nonZeroEntries = entries.filter(([key]) => counts[key].length > 0);
+  if (nonZeroEntries.length === 0) {
+    lines.push('  (no changes)', '');
+    return;
+  }
+
+  for (const [key, label] of nonZeroEntries) {
+    lines.push(`  ${label}: ${counts[key].length}`);
+  }
+
+  lines.push('');
+}
+
+function printArchiveSection(lines, counts) {
+  const title = `${SECTION_LABELS.archive.padEnd(9, ' ')} (.agents/workspace/archive/):`;
+  lines.push(title);
+
+  if (counts.copied.length === 0 && counts.skipped.length === 0) {
+    lines.push('  (no changes)', '');
+    return;
+  }
+
+  if (counts.copied.length > 0) {
+    lines.push(`  ✓ Copied  : ${counts.copied.length}`);
+  }
+  if (counts.skipped.length > 0) {
+    lines.push(`  ⊘ Skipped : ${counts.skipped.length}`);
+  }
+  lines.push('');
+}
+
+function renderDetail(entry) {
+  if (entry.action === 'moved') {
+    return `  ${entry.symbol} ${entry.taskId}  ${entry.fromSection}→${entry.toSection}  ${entry.detail}`;
+  }
+
+  const label = entry.section.padEnd(9, ' ');
+  return `  ${entry.symbol} ${entry.taskId}  ${label} ${entry.detail}`;
+}
+
+function printReport(report) {
+  const mutableTotals = MUTABLE_SECTIONS.reduce((acc, section) => {
+    acc.copied += report.sections[section].copied.length;
+    acc.updated += report.sections[section].updated.length;
+    acc.moved += report.sections[section].moved.length;
+    acc.skipped += report.sections[section].skipped.length;
+    return acc;
+  }, { copied: 0, updated: 0, moved: 0, skipped: 0 });
+
+  const archiveTotals = {
+    copied: report.sections.archive.copied.length,
+    skipped: report.sections.archive.skipped.length
+  };
+
+  const lines = [
+    'Merge summary',
+    DIVIDER,
+    `Source: ${report.sourcePath}`,
+    `Backup: ${report.backupRoot}`,
+    ''
+  ];
+
+  for (const section of MUTABLE_SECTIONS) {
+    printSection(lines, section, report.sections[section]);
+  }
+  printArchiveSection(lines, report.sections.archive);
+
+  lines.push(
+    DIVIDER,
+    `Totals: ${mutableTotals.copied + archiveTotals.copied} copied, ${mutableTotals.updated} updated, ${mutableTotals.moved} moved, ${mutableTotals.skipped + archiveTotals.skipped} skipped`,
+    `Backup contains ${report.backupCount} task(s); review and remove when verified.`,
+    '',
+    'Detailed log:'
+  );
+
+  if (report.details.length === 0) {
+    lines.push('  (none)');
+  } else {
+    for (const detail of report.details) {
+      lines.push(renderDetail(detail));
+    }
+  }
+
+  process.stdout.write(`${lines.join('\n')}\n`);
+}
+
+async function cmdMerge(args) {
+  const sourcePath = args[0];
+  if (!sourcePath) {
+    throw new Error('Usage: agent-infra merge <source-path>');
+  }
+
+  const resolvedSource = path.resolve(sourcePath);
+  if (!fs.existsSync(resolvedSource)) {
+    throw new Error(`Source path does not exist: ${sourcePath}`);
+  }
+
+  if (!fs.statSync(resolvedSource).isDirectory()) {
+    throw new Error(`Source path is not a directory: ${sourcePath}`);
+  }
+
+  const workspaceDir = path.join(process.cwd(), '.agents', 'workspace');
+  const archiveDir = path.join(workspaceDir, 'archive');
+  const backupStamp = formatBackupTimestamp(new Date());
+  const backupRootRelative = `.agents/workspace/.merge-backup/${backupStamp}/`;
+  const backupRoot = path.join(workspaceDir, '.merge-backup', backupStamp);
+  const report = createReport(resolvedSource, backupRootRelative);
+  const mode = detectSourceMode(resolvedSource);
+
+  for (const section of ALL_SECTIONS) {
+    fs.mkdirSync(path.join(workspaceDir, section), { recursive: true });
+  }
+
+  if (mode === 'legacy-archive') {
+    info('Detected legacy archive source; treating the input as archive-only for backward compatibility.');
+    mergeArchiveSection(resolvedSource, archiveDir, report);
+  } else {
+    mergeMutableSections({
+      sourceWorkspace: resolvedSource,
+      localWorkspace: workspaceDir,
+      backupRoot,
+      report
+    });
+
+    const sourceArchive = path.join(resolvedSource, 'archive');
+    if (fs.existsSync(sourceArchive) && fs.statSync(sourceArchive).isDirectory()) {
+      mergeArchiveSection(sourceArchive, archiveDir, report);
+    }
+  }
+
+  rebuildManifests(archiveDir);
+
+  if (mode === 'legacy-archive') {
+    printLegacyArchiveMessages(report, sourcePath);
+  }
+
+  printReport(report);
 }
 
 export {
   cmdMerge,
+  compareTimestamps,
+  detectSourceMode,
   extractField,
   extractTitle,
+  formatBackupTimestamp,
+  getTaskTimestamp,
   rebuildManifests,
   scanSourceTasks,
+  scanWorkspaceSection,
   taskExistsInArchive
 };