@fitlab-ai/agent-infra 0.11.5 → 0.11.6

package/lib/sandbox/config.ts

@@ -18,6 +18,7 @@ const DEFAULTS = Object.freeze({
   tools: ['agent-infra'],
   refreshIntervalDays: 7,
   dockerfile: null,
+  initCommand: null,
   vm: {
     cpu: null,
     memory: null,
@@ -35,6 +36,7 @@ type SandboxConfigInput = {
   customTools?: unknown;
   refreshIntervalDays?: unknown;
   dockerfile?: string | null;
+  initCommand?: unknown;
   vm?: Record<string, unknown>;
 };
 
@@ -66,6 +68,7 @@ export type SandboxConfig = {
   delivery?: { remote: string; baseRef: string };
   refreshIntervalDays: number;
   dockerfile: string | null;
+  initCommand: string | null;
   vm: SandboxVmConfig;
 };
 
@@ -103,6 +106,7 @@ function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes:
     tools: [...DEFAULTS.tools],
     refreshIntervalDays: DEFAULTS.refreshIntervalDays,
     dockerfile: DEFAULTS.dockerfile,
+    initCommand: DEFAULTS.initCommand,
     vm: { ...DEFAULTS.vm }
   };
 }
@@ -149,6 +153,13 @@ export function loadConfig({
     ? [...sandbox.runtimes]
     : defaults.runtimes;
   const dockerfile = typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null;
+  if (sandbox.initCommand !== undefined &&
+      (typeof sandbox.initCommand !== 'string' || sandbox.initCommand.trim().length === 0)) {
+    throw new Error('sandbox.initCommand must be a non-empty string when configured');
+  }
+  const initCommand = typeof sandbox.initCommand === 'string'
+    ? sandbox.initCommand
+    : null;
 
   if (!dockerfile) {
     let enginesNode: string | undefined;
@@ -200,6 +211,7 @@ export function loadConfig({
       defaults.refreshIntervalDays
     ),
     dockerfile,
+    initCommand,
     vm: {
       cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,
       memory: asPositiveNumberOrNull(sandbox.vm?.memory) ?? defaults.vm.memory,

package/lib/sandbox/control/lifecycle.ts

@@ -1298,6 +1298,10 @@ export async function quiesceSandboxControlRoot(
     timeoutMs?: number;
     timing?: SandboxControlTimingPolicy;
     identityProbe?: ProcessIdentityProbe;
+    executionProcessControl?: Readonly<{
+      isAlive: (execution: SandboxControlExecution) => boolean;
+      terminate: (execution: SandboxControlExecution, phase: 'graceful' | 'force') => boolean;
+    }>;
   } = {}
 ): Promise<'missing' | 'stale' | 'stopped'> {
   const resolvedRoot = path.resolve(root);
@@ -1338,58 +1342,63 @@ export async function quiesceSandboxControlRoot(
   if (!manifest && brokerLive) throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
 
   const platform = options.platform ?? process.platform;
+  const processControl = options.executionProcessControl ?? {
+    isAlive: (execution: SandboxControlExecution) => executionAlive(execution, platform, identityProbe),
+    terminate: (execution: SandboxControlExecution, phase: 'graceful' | 'force') => phase === 'graceful'
+      ? terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe })
+      : terminateSandboxControlExecution(execution, {
+        platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now(), identityProbe
+      })
+  };
   let executions = manifest ? readExecutions(manifest) : [];
   const owner: OwnerIdentity | null = brokerLive ? broker : statusLive ? statusOwner : null;
   if (!owner) {
     if (manifest && !broker && !status) throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
     for (const execution of executions) {
-      terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
+      processControl.terminate(execution, 'graceful');
     }
     const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
     while (Date.now() < softDeadlineAt) {
-      if (!executions.some((execution) => executionAlive(execution, platform, identityProbe))) break;
+      if (!executions.some((execution) => processControl.isAlive(execution))) break;
       await new Promise((resolve) => setTimeout(resolve, 25));
     }
     if (manifest) executions = mergeExecutions(executions, readExecutions(manifest));
     if (Date.now() >= deadlineAt) throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
     for (const execution of executions) {
-      if (!terminateSandboxControlExecution(execution, {
-        platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now(), identityProbe
-      })) {
+      if (!processControl.terminate(execution, 'force')) {
         throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
       }
     }
-    if (executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
+    if (executions.some((execution) => processControl.isAlive(execution))) {
       throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
     }
     return broker || status ? 'stale' : 'missing';
   }
 
-  const remaining = (): number => Math.max(0, deadlineAt - Date.now());
   signalOwner(owner, platform, false);
   for (const execution of executions) {
-    terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
+    processControl.terminate(execution, 'graceful');
   }
   const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
   while (Date.now() < softDeadlineAt) {
-    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe))) break;
+    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution))) break;
     await new Promise((resolve) => setTimeout(resolve, 25));
   }
-  if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
+  if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution))) {
     return 'stopped';
   }
   if (manifest) executions = mergeExecutions(executions, readExecutions(manifest));
   if (Date.now() >= deadlineAt) throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
   for (const execution of executions) {
-    terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, deadlineAt, forceAt: Date.now(), identityProbe });
+    processControl.terminate(execution, 'force');
   }
   signalOwner(owner, platform, true);
   while (Date.now() < deadlineAt) {
-    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe))) return 'stopped';
+    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution))) return 'stopped';
     await new Promise((resolve) => setTimeout(resolve, 25));
   }
   if (ownerLive(owner, identityProbe)) throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
-  if (executions.some((execution) => executionAlive(execution, platform, identityProbe))) throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+  if (executions.some((execution) => processControl.isAlive(execution))) throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
   return 'stopped';
 }
 

package/lib/sandbox/task-resolver.ts

@@ -36,7 +36,9 @@ function stripQuotes(value: string): string {
 
 function readTaskContent(repoRoot: string, taskId: string): { content: string; state: TaskWorkspaceState; taskMd: string } {
   for (const state of TASK_WORKSPACE_STATES) {
-    const taskPath = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
+    const taskPath = state === 'archive'
+      ? path.join(repoRoot, '.agents', 'workspace', state, ...findArchiveTaskParts(repoRoot, taskId), 'local', 'task.md')
+      : path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
     if (fs.existsSync(taskPath)) {
       return { content: fs.readFileSync(taskPath, 'utf8'), state, taskMd: taskPath };
     }
@@ -45,7 +47,7 @@ function readTaskContent(repoRoot: string, taskId: string): { content: string; s
 }
 
 function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspace[] {
-  return TASK_WORKSPACE_STATES.flatMap((state) => {
+  const hot = TASK_WORKSPACE_STATES.filter((state) => state !== 'archive').flatMap((state) => {
     const taskMd = path.join(repoRoot, '.agents', 'workspace', state, taskId, 'task.md');
     if (!fs.existsSync(taskMd)) return [];
     const content = fs.readFileSync(taskMd, 'utf8');
@@ -56,6 +58,32 @@ function taskWorkspaceCandidates(repoRoot: string, taskId: string): TaskWorkspac
       taskMd
     }];
   });
+  const parts = findArchiveTaskParts(repoRoot, taskId);
+  if (parts.length === 0) return hot;
+  const taskMd = path.join(repoRoot, '.agents', 'workspace', 'archive', ...parts, 'local', 'task.md');
+  if (!fs.existsSync(taskMd)) return hot;
+  const content = fs.readFileSync(taskMd, 'utf8');
+  return [...hot, {
+    taskId,
+    branch: resolveBranchFromTaskContent(content, taskId),
+    state: 'archive',
+    taskMd
+  }];
+}
+
+function findArchiveTaskParts(repoRoot: string, taskId: string): string[] {
+  const archiveRoot = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  if (!fs.existsSync(archiveRoot)) return [];
+  for (const year of fs.readdirSync(archiveRoot).sort().reverse()) {
+    if (!/^\d{4}$/.test(year)) continue;
+    for (const month of fs.readdirSync(path.join(archiveRoot, year)).sort().reverse()) {
+      if (!/^\d{2}$/.test(month)) continue;
+      for (const day of fs.readdirSync(path.join(archiveRoot, year, month)).sort().reverse()) {
+        if (/^\d{2}$/.test(day) && fs.existsSync(path.join(archiveRoot, year, month, day, taskId, 'local', 'task.md'))) return [year, month, day, taskId];
+      }
+    }
+  }
+  return [];
 }
 
 function resolveBranchFromTaskContent(content: string, taskId: string): string {
@@ -102,6 +130,27 @@ export function resolveTaskWorkspace(taskId: string, repoRoot: string): TaskWork
 
 export function listTaskWorkspaces(repoRoot: string, state: TaskWorkspaceState): TaskWorkspace[] {
   const stateRoot = path.join(repoRoot, '.agents', 'workspace', state);
+  if (state === 'archive') {
+    if (!fs.existsSync(stateRoot)) return [];
+    const rows: TaskWorkspace[] = [];
+    for (const year of fs.readdirSync(stateRoot).sort()) {
+      if (!/^\d{4}$/.test(year)) continue;
+      for (const month of fs.readdirSync(path.join(stateRoot, year)).sort()) {
+        if (!/^\d{2}$/.test(month)) continue;
+        for (const day of fs.readdirSync(path.join(stateRoot, year, month)).sort()) {
+          if (!/^\d{2}$/.test(day)) continue;
+          for (const taskId of fs.readdirSync(path.join(stateRoot, year, month, day)).sort()) {
+            if (!TASK_ID_RE.test(taskId)) continue;
+            const taskMd = path.join(stateRoot, year, month, day, taskId, 'local', 'task.md');
+            if (!fs.existsSync(taskMd)) continue;
+            const content = fs.readFileSync(taskMd, 'utf8');
+            rows.push({ taskId, branch: resolveBranchFromTaskContent(content, taskId), state, taskMd });
+          }
+        }
+      }
+    }
+    return rows;
+  }
   if (!fs.existsSync(stateRoot)) return [];
   return fs.readdirSync(stateRoot, { withFileTypes: true })
     .filter((entry) => entry.isDirectory() && TASK_ID_RE.test(entry.name))

package/lib/task/resolve-ref.ts

@@ -81,7 +81,7 @@ function listSortedNumeric(dir: string, width: number): string[] {
 }
 
 function findInArchive(repoRoot: string, taskId: string): string | null {
-  // archive-tasks SKILL writes to .agents/workspace/archive/YYYY/MM/DD/{taskId}/task.md
+  // archive-tasks stores local material at .agents/workspace/archive/YYYY/MM/DD/{taskId}/local/task.md
   // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
   // the task id's creation date. So we cannot derive the path from taskId alone;
   // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
@@ -91,7 +91,7 @@ function findInArchive(repoRoot: string, taskId: string): string | null {
     for (const month of listSortedNumeric(yearDir, 2)) {
       const monthDir = path.join(yearDir, month);
       for (const day of listSortedNumeric(monthDir, 2)) {
-        const candidate = path.join(monthDir, day, taskId, 'task.md');
+        const candidate = path.join(monthDir, day, taskId, 'local', 'task.md');
         if (fs.existsSync(candidate)) return candidate;
       }
     }
@@ -162,7 +162,7 @@ function enumerateAllTaskDirs(repoRoot: string): { taskId: string; taskDir: stri
       const monthDir = path.join(yearDir, month);
       for (const day of listSortedNumeric(monthDir, 2).reverse()) {
         const dayDir = path.join(monthDir, day);
-        for (const taskId of fs.readdirSync(dayDir).sort()) add(taskId, path.join(dayDir, taskId), 'archive');
+        for (const taskId of fs.readdirSync(dayDir).sort()) add(taskId, path.join(dayDir, taskId, 'local'), 'archive');
       }
     }
   }

package/lib/task/write.ts

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 
 import { isValidAgentInfraVersion, VERSION } from '../version.ts';
 import {
@@ -223,7 +224,7 @@ function errorDetails(error: unknown, fallback: TaskWriteErrorCode): TaskWriteEr
   };
 }
 
-function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): TaskWriteResult {
+function writeTaskCore(request: TaskWriteRequest, options: TaskWriteOptions = {}): TaskWriteResult {
   const resolved = options.taskLocation
     ? {
         ok: true as const,
@@ -479,6 +480,119 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
   return { ...successBase, status: 'applied', changed: true };
 }
 
+function archiveContentsHash(localDir: string): string {
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.name.includes('\n') || entry.name.includes('\r') || entry.name === 'manifest.md') {
+        throw new Error(`Archive source path is not valid: ${path.join(dir, entry.name)}`);
+      }
+      const target = path.join(dir, entry.name);
+      const stat = fs.lstatSync(target);
+      if (stat.isSymbolicLink()) throw new Error(`Archive source cannot contain symbolic links: ${target}`);
+      if (stat.isDirectory()) walk(target);
+      else if (stat.isFile()) {
+        if (entry.name !== 'contents.sha256') files.push(target);
+      }
+      else throw new Error(`Archive source cannot contain special files: ${target}`);
+    }
+  };
+  walk(localDir);
+  const rows = files
+    .map((file) => ({ file, relative: path.relative(localDir, file).split(path.sep).join('/') }))
+    .sort((left, right) => Buffer.compare(Buffer.from(left.relative), Buffer.from(right.relative)))
+    .map(({ file, relative }) => `${crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')}  ${relative}`);
+  return `${rows.join('\n')}${rows.length ? '\n' : ''}`;
+}
+
+function writeArchiveContentsHash(localDir: string): void {
+  const contents = archiveContentsHash(localDir);
+  const hashPath = path.join(localDir, 'contents.sha256');
+  const tempPath = path.join(localDir, `.contents.sha256.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`);
+  try {
+    fs.writeFileSync(tempPath, contents, { flag: 'wx' });
+    fs.renameSync(tempPath, hashPath);
+  } catch (error) {
+    try {
+      fs.unlinkSync(tempPath);
+    } catch (cleanupError) {
+      if ((cleanupError as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}; failed to remove ${tempPath}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+      }
+    }
+    throw error;
+  }
+}
+
+function restoreArchivedTask(taskMdPath: string, contents: Buffer, mode: number): void {
+  const tempPath = `${taskMdPath}.${process.pid}.${Math.random().toString(36).slice(2)}.rollback`;
+  fs.writeFileSync(tempPath, contents, { flag: 'wx', mode });
+  try {
+    fs.renameSync(tempPath, taskMdPath);
+  } catch (error) {
+    try {
+      fs.unlinkSync(tempPath);
+    } catch (cleanupError) {
+      if ((cleanupError as NodeJS.ErrnoException).code !== 'ENOENT') {
+        throw new Error(`${error instanceof Error ? error.message : String(error)}; failed to remove ${tempPath}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}`);
+      }
+    }
+    throw error;
+  }
+}
+
+function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): TaskWriteResult {
+  const resolved = options.taskLocation
+    ? {
+        ok: true as const,
+        repoRoot: options.taskLocation.repoRoot,
+        taskId: options.taskLocation.taskId,
+        taskDir: path.dirname(options.taskLocation.taskMdPath),
+        taskMdPath: options.taskLocation.taskMdPath,
+        state: options.taskLocation.state
+      }
+    : resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) {
+    return failure(request, { taskId: resolved.taskId, taskMdPath: null, actualState: null }, resolved.code, resolved.message);
+  }
+  if (resolved.state !== 'archive' || request.expectedState !== 'archive' || request.dryRun) {
+    return writeTaskCore(request, { ...options, taskLocation: {
+      repoRoot: resolved.repoRoot,
+      taskId: resolved.taskId,
+      taskMdPath: resolved.taskMdPath,
+      state: resolved.state
+    } });
+  }
+
+  const identity = { taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, actualState: resolved.state };
+  try {
+    const originalTask = fs.readFileSync(resolved.taskMdPath);
+    const originalMode = fs.statSync(resolved.taskMdPath).mode;
+    archiveContentsHash(resolved.taskDir);
+    const result = writeTaskCore(request, { ...options, taskLocation: {
+      repoRoot: resolved.repoRoot,
+      taskId: resolved.taskId,
+      taskMdPath: resolved.taskMdPath,
+      state: resolved.state
+    } });
+    if (result.status === 'applied') {
+      try {
+        writeArchiveContentsHash(resolved.taskDir);
+      } catch (error) {
+        try {
+          restoreArchivedTask(resolved.taskMdPath, originalTask, originalMode);
+        } catch (rollbackError) {
+          throw new Error(`Archive checksum update failed: ${error instanceof Error ? error.message : String(error)}; task rollback failed: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`);
+        }
+        throw error;
+      }
+    }
+    return result;
+  } catch (error) {
+    return failure(request, identity, 'TASK_READ_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
 export { writeTask, captureTaskWriteMetadata, canonicalTimestamp };
 export type {
   FrontmatterMutation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.5",
+  "version": "0.11.6",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/evidence-reporting.en.md

@@ -21,8 +21,7 @@ Record a reproducible command or entry point, the exact file/line/object/version
 - Preserve artifact SHA-256, semantic digest, review head, receipt, request-id, snapshot tree, and platform marker exactly.
 - The Issue continues to mirror the complete report; the report must not depend on logs accessible only on the local machine.
 - Manual validation keeps its stricter basename-only and sanitized-result rules; this shared rule does not expand public fields.
-- A `$ ` command line satisfies the structural gate but does not require complete successful output.
 
 ## Evidence Pairing
 
-Pair every verification claim with a `$ ` command and a proportionate result summary. Include a decisive raw excerpt only for failure, blocking, or dispute conclusions. When a command contains sensitive arguments, use its allowed public name or a redacted command.
+Pair every verification claim with an executable command and a proportionate result summary. Include a decisive raw excerpt only for failure, blocking, or dispute conclusions. When a command contains sensitive arguments, use its allowed public name or a redacted command.

package/templates/.agents/rules/evidence-reporting.zh-CN.md

@@ -21,8 +21,7 @@
 - artifact SHA-256、semantic digest、review head、receipt、request-id、快照树和平台 marker 必须精确保留。
 - Issue 继续镜像报告全文；报告不得依赖只有本机可访问的日志。
 - 人工验证继续使用 basename-only、sanitized result 等更严格规则；共享规则不扩大可公开字段。
-- `$ ` 命令行标记满足结构门禁，但不要求附带完整成功输出。
 
 ## 证据配对
 
-报告中的每个验证断言都应配一个 `$ ` 命令和相称结果摘要；只有失败、阻塞或争议结论才附决定性原文摘录。命令含敏感参数时使用允许公开的命令名或脱敏命令。
+报告中的每个验证断言都应配一个可执行命令和相称结果摘要；只有失败、阻塞或争议结论才附决定性原文摘录。命令含敏感参数时使用允许公开的命令名或脱敏命令。

package/templates/.agents/skills/archive-tasks/SKILL.en.md

@@ -7,7 +7,7 @@ description: >
 
 # Archive Completed Tasks
 
-Move completed tasks from `.agents/workspace/completed/` into `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/` and rebuild a three-level archive index:
+Archive completed tasks from `.agents/workspace/completed/` into `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/local/` and rebuild a three-level archive index. Local task materials live in `local/` with a path-sorted `contents.sha256`; the TASK root contains no ordinary files.
 - root manifest: `.agents/workspace/archive/manifest.md`
 - yearly manifest: `.agents/workspace/archive/YYYY/manifest.md`
 - monthly manifest: `.agents/workspace/archive/YYYY/MM/manifest.md`
@@ -32,7 +32,7 @@ bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before
 
 The script is responsible for:
 - reading `completed_at` from `task.md` frontmatter and falling back to `updated_at`
-- moving task directories directly into `YYYY/MM/DD/TASK-xxx/` without compression
+- storing local task materials under `YYYY/MM/DD/TASK-xxx/local/` without compression
 - skipping already archived, missing, or malformed tasks
 - rebuilding root, yearly, and monthly manifests from all archived tasks
 - printing an archive and skip summary

package/templates/.agents/skills/archive-tasks/SKILL.zh-CN.md

@@ -7,7 +7,7 @@ description: >
 
 # 归档已完成任务
 
-将 `.agents/workspace/completed/` 中的已完成任务移动到 `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/`，并重建三级归档索引：
+将 `.agents/workspace/completed/` 中的已完成任务归档到 `.agents/workspace/archive/YYYY/MM/DD/TASK-xxx/local/`，并重建三级归档索引。TASK 本地材料位于 `local/`，含按路径排序的 `contents.sha256`；TASK 根目录不存放普通文件。
 - 根 manifest：`.agents/workspace/archive/manifest.md`
 - 年 manifest：`.agents/workspace/archive/YYYY/manifest.md`
 - 月 manifest：`.agents/workspace/archive/YYYY/MM/manifest.md`
@@ -32,7 +32,7 @@ bash .agents/skills/archive-tasks/scripts/archive-tasks.sh [--days N | --before
 
 脚本负责：
 - 解析 `task.md` frontmatter 中的 `completed_at`（缺失时回退到 `updated_at`）
-- 按 `YYYY/MM/DD/TASK-xxx/` 目录直接移动任务，不压缩
+- 按 `YYYY/MM/DD/TASK-xxx/local/` 保存任务本地材料，不压缩
 - 跳过已归档、缺少元数据或不存在的任务
 - 全量重建根 / 年 / 月三级 manifest
 - 输出归档与跳过摘要

package/templates/.agents/skills/archive-tasks/scripts/archive-tasks.sh

@@ -8,9 +8,14 @@ WORKSPACE_ROOT="$REPO_ROOT/.agents/workspace"
 COMPLETED_DIR="$WORKSPACE_ROOT/completed"
 ARCHIVE_DIR="$WORKSPACE_ROOT/archive"
 MANIFEST_PATH="$ARCHIVE_DIR/manifest.md"
+tmpdir=""
+cleanup() {
+  [ -z "$tmpdir" ] || rm -rf "$tmpdir"
+}
+trap 'cleanup' 0
+trap 'cleanup; exit 1' HUP INT TERM
 
-tmpdir="$(mktemp -d)"
-trap 'rm -rf "$tmpdir"' EXIT HUP INT TERM
+tmpdir="$(mktemp -d "$WORKSPACE_ROOT/.archive-tmp.XXXXXX")"
 
 IDS_FILE="$tmpdir/task-ids.txt"
 : > "$IDS_FILE"
@@ -160,6 +165,17 @@ archive_task_dir() {
     return 0
   fi
 
+  find "$task_dir" -name manifest.md -print > "$tmpdir/task-manifests.txt"
+  if [ -s "$tmpdir/task-manifests.txt" ]; then
+    echo "TASK content cannot contain manifest.md: $task_id" >&2
+    return 1
+  fi
+  find "$task_dir" ! -type f ! -type d -print > "$tmpdir/task-special-files.txt"
+  if [ -s "$tmpdir/task-special-files.txt" ]; then
+    echo "TASK content cannot contain symbolic links or special files: $task_id" >&2
+    return 1
+  fi
+
   completed_at=$(extract_completed_at "$task_file")
   task_date=$(printf '%s' "$completed_at" | cut -c1-10)
 
@@ -179,12 +195,89 @@ archive_task_dir() {
     return 0
   fi
 
-  mkdir -p "$ARCHIVE_DIR/$year/$month/$day"
-  mv "$task_dir" "$destination_dir"
+  mkdir -p "$(dirname "$destination_dir")"
+  staged_dir="$tmpdir/$task_id"
+  mkdir -p "$staged_dir/local"
+  cp -R "$task_dir"/. "$staged_dir/local/"
+  write_contents_hash "$staged_dir/local"
+  mv "$staged_dir" "$destination_dir"
+  if ! rm -rf "$task_dir"; then
+    if ! rm -rf "$destination_dir"; then
+      echo "Failed to remove completed task and roll back archive copy: $task_id" >&2
+    else
+      echo "Failed to remove completed task; rolled back archive copy: $task_id" >&2
+    fi
+    return 1
+  fi
   archived_count=$((archived_count + 1))
   printf 'Archived %s -> %s\n' "$task_id" "$relative_path"
 }
 
+write_contents_hash() {
+  local_dir="$1"
+  hash_path=${2:-$local_dir/contents.sha256}
+  hash_tmp="$tmpdir/contents.sha256"
+  newline='
+'
+  : > "$hash_tmp"
+  find "$local_dir" -type f ! -name contents.sha256 | LC_ALL=C sort | while IFS= read -r source_file; do
+    relative_file=${source_file#"$local_dir"/}
+    case "$relative_file" in *"$newline"*|*"$(printf '\r')"*) echo "Newline path is not supported" >&2; return 1 ;; esac
+    if command -v sha256sum >/dev/null 2>&1; then
+      digest=$(sha256sum "$source_file" | awk '{print $1}')
+    else
+      digest=$(shasum -a 256 "$source_file" | awk '{print $1}')
+    fi
+    printf '%s  %s\n' "$digest" "$relative_file" >> "$hash_tmp"
+  done
+  mv "$hash_tmp" "$hash_path"
+  if [ "$hash_path" = "$local_dir/contents.sha256" ] && command -v sha256sum >/dev/null 2>&1; then
+    (cd "$local_dir" && sha256sum -c contents.sha256 >/dev/null)
+  elif [ "$hash_path" = "$local_dir/contents.sha256" ]; then
+    (cd "$local_dir" && shasum -a 256 -c contents.sha256 >/dev/null)
+  fi
+}
+
+validate_source_hash() {
+  source_dir="$1"
+  [ -f "$source_dir/task.md" ] || { echo "Archive source lacks task.md: $source_dir" >&2; return 1; }
+  [ -f "$source_dir/contents.sha256" ] || { echo "Archive source lacks contents.sha256: $source_dir" >&2; return 1; }
+  write_contents_hash "$source_dir" "$tmpdir/contents.expected"
+  if ! cmp -s "$tmpdir/contents.expected" "$source_dir/contents.sha256"; then
+    echo "Archive source checksum mismatch: $source_dir" >&2
+    return 1
+  fi
+}
+
+validate_existing_archive() {
+  [ -d "$ARCHIVE_DIR" ] || return 0
+  for year_dir in "$ARCHIVE_DIR"/[0-9][0-9][0-9][0-9]; do
+    [ -d "$year_dir" ] || continue
+    for month_dir in "$year_dir"/[0-9][0-9]; do
+      [ -d "$month_dir" ] || continue
+      for day_dir in "$month_dir"/[0-9][0-9]; do
+        [ -d "$day_dir" ] || continue
+        for task_dir in "$day_dir"/TASK-*; do
+          [ -d "$task_dir" ] || continue
+          [ -d "$task_dir/local" ] || { echo "Unsupported legacy archive task layout: $task_dir" >&2; return 1; }
+          for task_entry in "$task_dir"/*; do
+            [ -e "$task_entry" ] || continue
+            case "$(basename "$task_entry")" in
+              local|github|derived) [ -d "$task_entry" ] || { echo "Invalid archive source directory: $task_entry" >&2; return 1; } ;;
+              *) echo "Unexpected TASK root entry: $task_entry" >&2; return 1 ;;
+            esac
+          done
+          find "$task_dir/local" -name manifest.md -print > "$tmpdir/task-manifests.txt"
+          [ ! -s "$tmpdir/task-manifests.txt" ] || { echo "TASK content cannot contain manifest.md: $task_dir" >&2; return 1; }
+          find "$task_dir/local" ! -type f ! -type d -print > "$tmpdir/task-special-files.txt"
+          [ ! -s "$tmpdir/task-special-files.txt" ] || { echo "TASK content cannot contain symbolic links or special files: $task_dir" >&2; return 1; }
+          validate_source_hash "$task_dir/local"
+        done
+      done
+    done
+  done
+}
+
 should_archive_filtered_task() {
   task_dir="$1"
   task_file="$task_dir/task.md"
@@ -231,7 +324,7 @@ rebuild_manifest() {
           [ -d "$task_dir" ] || continue
 
           task_id=$(basename "$task_dir")
-          task_file="$task_dir/task.md"
+          task_file="$task_dir/local/task.md"
           relative_path="$year/$month/$day/$task_id/"
           title="$task_id"
           task_type="unknown"
@@ -261,7 +354,15 @@ rebuild_manifest() {
     done
   done
 
-  find "$ARCHIVE_DIR" -type f -name 'manifest.md' -exec rm -f {} \;
+  rm -f "$ARCHIVE_DIR/manifest.md"
+  for year_dir in "$ARCHIVE_DIR"/[0-9][0-9][0-9][0-9]; do
+    [ -d "$year_dir" ] || continue
+    rm -f "$year_dir/manifest.md"
+    for month_dir in "$year_dir"/[0-9][0-9]; do
+      [ -d "$month_dir" ] || continue
+      rm -f "$month_dir/manifest.md"
+    done
+  done
 
   awk -F'\t' '{print $1 "\t" $2}' "$entries_file" | LC_ALL=C sort -u > "$month_keys_file"
   awk -F'\t' '{print $1}' "$entries_file" | LC_ALL=C sort -u > "$year_keys_file"
@@ -436,6 +537,8 @@ if [ -s "$IDS_FILE" ]; then
   MODE="ids"
 fi
 
+validate_existing_archive
+
 archived_count=0
 skipped_count=0