minimal-agent 0.11.0 → 0.13.0

package/src/session/runAgentTurn.ts

@@ -1,11 +1,22 @@
-import { buildBaseSystemPrompt, buildTransientPromptBundle } from '../prompts/system.js';
+import {
+  buildBaseSystemPrompt,
+  buildTransientPromptBundle,
+} from '../prompts/system.js';
 import { ALL_TOOLS } from '../tools/index.js';
 import type { LoopEvent, Provider } from '../types.js';
 import { sessionFileFor } from '../context/sessionPath.js';
-import { getOrCreateSessionState, sessionStateKey, type SessionState } from './sessionState.js';
+import {
+  getOrCreateSessionState,
+  sessionStateKey,
+  type SessionState,
+} from './sessionState.js';
+import { hydrateSessionWorktree } from '../tools/worktree/sessionWorktree.js';
 import { runTurn } from './runTurn.js';
 import { withWorkingDir } from '../bootstrap/workingDir.js';
-import { listSessionSummaries, updateSessionMetadata } from '../context/sessionRegistry.js';
+import {
+  listSessionSummaries,
+  updateSessionMetadata,
+} from '../context/sessionRegistry.js';
 import { workspaceIndexService } from '../context/workspaceIndex.js';
 import { configService } from '../config/configService.js';
 import { createPromptCacheContext } from '../llm/promptCache.js';
@@ -44,55 +55,86 @@ export async function runAgentTurn(
   deps: { runTurn?: typeof runTurn } = {},
 ): Promise<RunAgentTurnResult> {
   const run = deps.runTurn ?? runTurn;
-  const session = (await listSessionSummaries(opts.cwd)).find((item) => item.id === opts.sessionId);
+  const session = (await listSessionSummaries(opts.cwd)).find(
+    (item) => item.id === opts.sessionId,
+  );
   let sessionModelId = session?.modelId;
   if (!opts.model && !sessionModelId) {
-    sessionModelId = (await configService.getSnapshot()).config?.baseModelId ?? undefined;
+    sessionModelId =
+      (await configService.getSnapshot()).config?.baseModelId ?? undefined;
     if (sessionModelId) {
-      await updateSessionMetadata(opts.cwd, opts.sessionId, { modelId: sessionModelId }).catch(() => {});
+      await updateSessionMetadata(opts.cwd, opts.sessionId, {
+        modelId: sessionModelId,
+      }).catch(() => {});
     }
   }
-  const sessionProvider = !opts.model && sessionModelId
-    ? await configService.providerForModel(sessionModelId)
-    : null;
+  const sessionProvider =
+    !opts.model && sessionModelId
+      ? await configService.providerForModel(sessionModelId)
+      : null;
   const provider = opts.model
     ? { ...opts.provider, model: opts.model }
-    : sessionProvider ?? opts.provider;
-  const workspace = await workspaceIndexService.register(opts.cwd).catch(() => undefined);
+    : (sessionProvider ?? opts.provider);
+  const workspace = await workspaceIndexService
+    .register(opts.cwd)
+    .catch(() => undefined);
   const sessionFile = sessionFileFor(opts.cwd, opts.sessionId);
   const events: LoopEvent[] = [];
   let result = '';
   let error: string | undefined;
   let numTurns = 0;
+  const turnSessionState =
+    opts.sessionState ??
+    getOrCreateSessionState(
+      sessionStateKey({
+        surface: 'headless',
+        workspaceId: workspace?.id,
+        cwd: workspace?.id ? undefined : opts.cwd,
+        sessionId: opts.sessionId,
+      }),
+    );
+  await hydrateSessionWorktree({
+    sessionState: turnSessionState,
+    workspaceId: workspace?.id,
+    sessionId: opts.sessionId,
+    cwd: opts.cwd,
+  });
+  const effectiveCwd = turnSessionState.activeWorktree?.path ?? opts.cwd;
 
-  await withWorkingDir(opts.cwd, async () => {
+  await withWorkingDir(effectiveCwd, async () => {
     // 稳定层进 history[0]（runTurn 每轮重写它，必须逐字节可复现，见 runTurn.ts 的缓存不变量）；
     // 易变层每轮单独计算，仅附加到当前用户消息的模型副本。
     const runtimeContext = createAgentRuntimeContext({
       surface: 'headless',
       profile: 'main',
-      cwd: opts.cwd,
+      cwd: effectiveCwd,
       workspaceId: workspace?.id,
       sessionId: opts.sessionId,
-      owner: opts.memoryAccess && opts.memoryAccess !== 'denied' ? 'local-owner' : 'untrusted',
+      owner:
+        opts.memoryAccess && opts.memoryAccess !== 'denied'
+          ? 'local-owner'
+          : 'untrusted',
       memoryAccess: opts.memoryAccess ?? 'denied',
       interactiveAsk: false,
     });
     const turnTools = filterToolsForRuntime(ALL_TOOLS, runtimeContext);
-    const systemPrompt = await buildBaseSystemPrompt(opts.cwd, turnTools);
+    const systemPrompt = await buildBaseSystemPrompt(effectiveCwd, turnTools);
     const transientBundle = await buildTransientPromptBundle({
-      cwd: opts.cwd,
+      cwd: effectiveCwd,
       tools: turnTools,
       runtime: {
         surface: 'headless',
-        cwd: opts.cwd,
+        cwd: effectiveCwd,
         workspaceId: workspace?.id,
+        sessionId: opts.sessionId,
         interactiveAsk: false,
         memoryAccess: runtimeContext.memoryAccess,
         currentUserInput: opts.input,
       },
     }).catch(() => undefined);
-    await updateSessionMetadata(opts.cwd, opts.sessionId, { lastMessagePreview: opts.input }).catch(() => {});
+    await updateSessionMetadata(opts.cwd, opts.sessionId, {
+      lastMessagePreview: opts.input,
+    }).catch(() => {});
     for await (const ev of run({
       userInput: opts.input,
       provider,
@@ -102,12 +144,7 @@ export async function runAgentTurn(
       promptCache: createPromptCacheContext(
         `workspace:${workspace?.id ?? opts.cwd}:session:${opts.sessionId}`,
       ),
-      sessionState: opts.sessionState ?? getOrCreateSessionState(sessionStateKey({
-        surface: runtimeContext.surface,
-        workspaceId: runtimeContext.workspaceId,
-        cwd: opts.cwd,
-        sessionId: opts.sessionId,
-      })),
+      sessionState: turnSessionState,
       signal: opts.signal,
       maxTurns: opts.maxTurns,
       runtimeContext,
@@ -120,7 +157,8 @@ export async function runAgentTurn(
         if (ev.type === 'assistant_message') numTurns++;
         // compact_failed 是非致命（loop 压缩失败后 snip 兜底继续跑完，types.ts 有约定；
         // print.ts 同样特判）——不置 error，否则 cron 会把自愈轮误判失败。
-        if (ev.type === 'error' && ev.code !== 'compact_failed') error = ev.error;
+        if (ev.type === 'error' && ev.code !== 'compact_failed')
+          error = ev.error;
       }
     }
   });
@@ -135,5 +173,9 @@ export async function runAgentTurn(
 }
 
 function isEventLike(ev: unknown): ev is LoopEvent {
-  return Boolean(ev && typeof ev === 'object' && typeof (ev as { type?: unknown }).type === 'string');
+  return Boolean(
+    ev &&
+    typeof ev === 'object' &&
+    typeof (ev as { type?: unknown }).type === 'string',
+  );
 }

package/src/session/runTurn.js

@@ -20,7 +20,7 @@
  */
 import { loadContext, saveContext } from '../context/persistContext.js';
 import { acquireContextLock } from '../context/contextLock.js';
-import { episodicMemoryService } from '../memory/episodicMemory.js';
+import { startTurnJournal } from '../memory/turnJournal.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
 /**
  * 已有历史时，用调用方新算好的 systemPrompt（含当前日期/实时扫描的 skills·plugins 清单/
@@ -55,23 +55,14 @@ export async function* runTurn(opts) {
     const loaded = opts.initialHistory ?? (persist ? await loadContext(opts.sessionFile) : null);
     const history = buildInitialHistory(loaded, opts.systemPrompt);
     const historyStart = history.length;
-    const memoryContext = opts.memoryContext;
-    const journalContext = memoryContext?.access !== 'denied'
-        && memoryContext?.workspaceId
-        && memoryContext?.sessionId
-        ? {
-            workspaceId: memoryContext.workspaceId,
-            sessionId: memoryContext.sessionId,
-        }
-        : null;
-    if (journalContext) {
-        await episodicMemoryService.append({
-            ...journalContext,
-            role: 'user',
-            content: opts.userInput,
-            messageId: opts.userMessageId,
-        }).catch(() => undefined);
-    }
+    // 会话原文记账：实现在 src/memory/turnJournal.ts（TUI 的 useChat 用同一份），
+    // 刻意不下沉到 runQuery —— 子 Agent 与 workflow 步也调 runQuery，记在那里会把
+    // 子任务提示词当成"用户说的话"污染历史检索。
+    const journal = await startTurnJournal({
+        memoryContext: opts.memoryContext,
+        userInput: opts.userInput,
+        ...(opts.userMessageId ? { userMessageId: opts.userMessageId } : {}),
+    });
     try {
         yield* runWithPlugins(opts.userInput, {
             provider: opts.provider,
@@ -83,6 +74,7 @@ export async function* runTurn(opts) {
             sessionState: opts.sessionState,
             chat: opts.chat,
             executeTool: opts.executeTool,
+            commitFormalDelivery: opts.commitFormalDelivery,
             toolGate: opts.toolGate,
             transientContext: opts.transientContext,
             transientBundle: opts.transientBundle,
@@ -102,17 +94,7 @@ export async function* runTurn(opts) {
     }
     finally {
         try {
-            if (journalContext) {
-                const assistant = lastAssistantMessage(history, historyStart);
-                const content = assistant ? messageText(assistant) : '';
-                if (content) {
-                    await episodicMemoryService.append({
-                        ...journalContext,
-                        role: 'assistant',
-                        content,
-                    }).catch(() => undefined);
-                }
-            }
+            await journal?.finish(history, historyStart);
             if (persist)
                 await saveContext(history, opts.sessionFile);
         }
@@ -121,20 +103,3 @@ export async function* runTurn(opts) {
         }
     }
 }
-function messageText(message) {
-    if (typeof message.content === 'string')
-        return message.content;
-    if (!Array.isArray(message.content))
-        return '';
-    return message.content
-        .filter((part) => part.type === 'text')
-        .map((part) => part.text)
-        .join('\n');
-}
-function lastAssistantMessage(messages, start) {
-    for (let index = messages.length - 1; index >= start; index -= 1) {
-        if (messages[index]?.role === 'assistant')
-            return messages[index];
-    }
-    return undefined;
-}

package/src/session/runTurn.ts

@@ -21,7 +21,7 @@
 
 import { loadContext, saveContext } from '../context/persistContext.js';
 import { acquireContextLock } from '../context/contextLock.js';
-import { episodicMemoryService } from '../memory/episodicMemory.js';
+import { startTurnJournal } from '../memory/turnJournal.js';
 import type { PluginEvent } from '../plugins/pluginApi.js';
 import { runWithPlugins } from '../plugins/pluginRunner.js';
 import type {
@@ -49,6 +49,7 @@ export interface RunTurnOptions {
    *  让测试用显式注入替代 mock.module(loop.js)——后者会全局泄漏污染其它测试文件。 */
   chat?: import('../plugins/pluginRunner.js').PluginRunnerOptions['chat'];
   executeTool?: import('../plugins/pluginRunner.js').PluginRunnerOptions['executeTool'];
+  commitFormalDelivery?: import('../plugins/pluginRunner.js').PluginRunnerOptions['commitFormalDelivery'];
   /** 工具执行闸门（生产用）：透传给 runWithPlugins→runQuery。见 src/toolGate.ts。 */
   toolGate?: import('../plugins/pluginRunner.js').PluginRunnerOptions['toolGate'];
   /** 只对本次模型回合可见，不写入 session。 */
@@ -111,24 +112,14 @@ export async function* runTurn(
   const loaded = opts.initialHistory ?? (persist ? await loadContext(opts.sessionFile) : null);
   const history: Message[] = buildInitialHistory(loaded, opts.systemPrompt);
   const historyStart = history.length;
-  const memoryContext = opts.memoryContext;
-  const journalContext = memoryContext?.access !== 'denied'
-    && memoryContext?.workspaceId
-    && memoryContext?.sessionId
-    ? {
-        workspaceId: memoryContext.workspaceId,
-        sessionId: memoryContext.sessionId,
-      }
-    : null;
-
-  if (journalContext) {
-    await episodicMemoryService.append({
-      ...journalContext,
-      role: 'user',
-      content: opts.userInput,
-      messageId: opts.userMessageId,
-    }).catch(() => undefined);
-  }
+  // 会话原文记账：实现在 src/memory/turnJournal.ts（TUI 的 useChat 用同一份），
+  // 刻意不下沉到 runQuery —— 子 Agent 与 workflow 步也调 runQuery，记在那里会把
+  // 子任务提示词当成"用户说的话"污染历史检索。
+  const journal = await startTurnJournal({
+    memoryContext: opts.memoryContext,
+    userInput: opts.userInput,
+    ...(opts.userMessageId ? { userMessageId: opts.userMessageId } : {}),
+  });
 
   try {
     yield* runWithPlugins(opts.userInput, {
@@ -141,6 +132,7 @@ export async function* runTurn(
       sessionState: opts.sessionState,
       chat: opts.chat,
       executeTool: opts.executeTool,
+      commitFormalDelivery: opts.commitFormalDelivery,
       toolGate: opts.toolGate,
       transientContext: opts.transientContext,
       transientBundle: opts.transientBundle,
@@ -159,36 +151,10 @@ export async function* runTurn(
     });
   } finally {
     try {
-      if (journalContext) {
-        const assistant = lastAssistantMessage(history, historyStart);
-        const content = assistant ? messageText(assistant) : '';
-        if (content) {
-          await episodicMemoryService.append({
-            ...journalContext,
-            role: 'assistant',
-            content,
-          }).catch(() => undefined);
-        }
-      }
+      await journal?.finish(history, historyStart);
       if (persist) await saveContext(history, opts.sessionFile);
     } finally {
       await release();
     }
   }
 }
-
-function messageText(message: Message): string {
-  if (typeof message.content === 'string') return message.content;
-  if (!Array.isArray(message.content)) return '';
-  return message.content
-    .filter((part): part is Extract<typeof part, { type: 'text' }> => part.type === 'text')
-    .map((part) => part.text)
-    .join('\n');
-}
-
-function lastAssistantMessage(messages: Message[], start: number): Message | undefined {
-  for (let index = messages.length - 1; index >= start; index -= 1) {
-    if (messages[index]?.role === 'assistant') return messages[index];
-  }
-  return undefined;
-}

package/src/session/runtimeStore.js

@@ -0,0 +1,149 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, readdir, rename, rm, stat, } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { agentStateDir } from '../context/agentHome.js';
+function segment(value, fallback) {
+    return ((value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
+        fallback);
+}
+export function sessionRuntimeDir(identity) {
+    return join(agentStateDir(), 'runtime', segment(identity.workspaceId, 'local'), segment(identity.sessionId, 'local'));
+}
+const queues = new Map();
+export async function withRuntimeFileLock(path, work) {
+    const key = resolve(path);
+    const previous = queues.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise((done) => {
+        release = done;
+    });
+    const tail = previous.then(() => current);
+    queues.set(key, tail);
+    await previous.catch(() => undefined);
+    let lockHandle;
+    const lockPath = `${path}.lock`;
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    try {
+        const deadline = Date.now() + 10_000;
+        while (!lockHandle) {
+            try {
+                lockHandle = await open(lockPath, 'wx', 0o600);
+                await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const age = Date.now() -
+                    (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+                if (age > 30_000)
+                    await rm(lockPath, { force: true });
+                else if (Date.now() >= deadline)
+                    throw new Error(`runtime lock timeout: ${path}`);
+                else
+                    await new Promise((r) => setTimeout(r, 25));
+            }
+        }
+        return await work();
+    }
+    finally {
+        await lockHandle?.close().catch(() => undefined);
+        if (lockHandle)
+            await rm(lockPath, { force: true }).catch(() => undefined);
+        release();
+        if (queues.get(key) === tail)
+            queues.delete(key);
+    }
+}
+export async function readRuntimeJson(path, fallback) {
+    try {
+        return JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return fallback;
+    }
+}
+export async function writeRuntimeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temp, 'wx', 0o600);
+        try {
+            await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temp, path);
+    }
+    finally {
+        await rm(temp, { force: true }).catch(() => undefined);
+    }
+}
+export async function mutateRuntimeJson(path, fallback, mutate) {
+    return withRuntimeFileLock(path, async () => {
+        const next = await mutate(await readRuntimeJson(path, fallback));
+        await writeRuntimeJson(path, next);
+        return next;
+    });
+}
+export async function removeManagedPath(path, expectedRoot) {
+    const target = resolve(path);
+    const root = resolve(expectedRoot);
+    const rel = target.slice(root.length);
+    if (target === root || !target.startsWith(`${root}/`) || rel.includes('\0')) {
+        throw new Error(`拒绝清理托管根目录之外的路径：${target}`);
+    }
+    await rm(target, { recursive: true, force: true });
+}
+export async function runtimeFileVersion(path) {
+    const info = await stat(path);
+    return `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`;
+}
+const activeOutputs = new Set();
+const OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+const OUTPUT_GLOBAL_LIMIT = 5 * 1024 * 1024 * 1024;
+let pruneOutputsPromise;
+export function registerRuntimeOutput(path) {
+    activeOutputs.add(resolve(path));
+}
+export function unregisterRuntimeOutput(path) {
+    activeOutputs.delete(resolve(path));
+}
+export function pruneRuntimeOutputs() {
+    pruneOutputsPromise ??= (async () => {
+        const root = join(agentStateDir(), 'runtime');
+        const files = [];
+        for (const workspace of await readdir(root).catch(() => [])) {
+            const workspaceDir = join(root, workspace);
+            for (const session of await readdir(workspaceDir).catch(() => [])) {
+                const outputDir = join(workspaceDir, session, 'outputs');
+                const sessionFiles = [];
+                for (const name of await readdir(outputDir).catch(() => [])) {
+                    const path = join(outputDir, name);
+                    const info = await stat(path).catch(() => undefined);
+                    if (info?.isFile() && !activeOutputs.has(resolve(path))) {
+                        sessionFiles.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+                    }
+                }
+                sessionFiles.sort((left, right) => right.mtimeMs - left.mtimeMs);
+                await Promise.all(sessionFiles
+                    .slice(50)
+                    .map((file) => rm(file.path, { force: true }).catch(() => undefined)));
+                files.push(...sessionFiles.slice(0, 50));
+            }
+        }
+        files.sort((left, right) => right.mtimeMs - left.mtimeMs);
+        let retainedBytes = 0;
+        const cutoff = Date.now() - OUTPUT_RETENTION_MS;
+        for (const file of files) {
+            retainedBytes += file.size;
+            if (file.mtimeMs < cutoff || retainedBytes > OUTPUT_GLOBAL_LIMIT) {
+                await rm(file.path, { force: true }).catch(() => undefined);
+            }
+        }
+    })().finally(() => {
+        pruneOutputsPromise = undefined;
+    });
+    return pruneOutputsPromise;
+}

package/src/session/runtimeStore.ts

@@ -0,0 +1,197 @@
+import { randomUUID } from 'node:crypto';
+import {
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  stat,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+
+import { agentStateDir } from '../context/agentHome.js';
+
+export interface RuntimeIdentity {
+  workspaceId?: string;
+  sessionId?: string;
+}
+
+function segment(value: string | undefined, fallback: string): string {
+  return (
+    (value ?? fallback).replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120) ||
+    fallback
+  );
+}
+
+export function sessionRuntimeDir(identity: RuntimeIdentity): string {
+  return join(
+    agentStateDir(),
+    'runtime',
+    segment(identity.workspaceId, 'local'),
+    segment(identity.sessionId, 'local'),
+  );
+}
+
+const queues = new Map<string, Promise<unknown>>();
+export async function withRuntimeFileLock<T>(
+  path: string,
+  work: () => Promise<T>,
+): Promise<T> {
+  const key = resolve(path);
+  const previous = queues.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((done) => {
+    release = done;
+  });
+  const tail = previous.then(() => current);
+  queues.set(key, tail);
+  await previous.catch(() => undefined);
+  let lockHandle: Awaited<ReturnType<typeof open>> | undefined;
+  const lockPath = `${path}.lock`;
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  try {
+    const deadline = Date.now() + 10_000;
+    while (!lockHandle) {
+      try {
+        lockHandle = await open(lockPath, 'wx', 0o600);
+        await lockHandle.writeFile(`${process.pid}\n${Date.now()}\n`);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+        const age =
+          Date.now() -
+          (await stat(lockPath).catch(() => ({ mtimeMs: Date.now() }))).mtimeMs;
+        if (age > 30_000) await rm(lockPath, { force: true });
+        else if (Date.now() >= deadline)
+          throw new Error(`runtime lock timeout: ${path}`);
+        else await new Promise((r) => setTimeout(r, 25));
+      }
+    }
+    return await work();
+  } finally {
+    await lockHandle?.close().catch(() => undefined);
+    if (lockHandle) await rm(lockPath, { force: true }).catch(() => undefined);
+    release();
+    if (queues.get(key) === tail) queues.delete(key);
+  }
+}
+
+export async function readRuntimeJson<T>(
+  path: string,
+  fallback: T,
+): Promise<T> {
+  try {
+    return JSON.parse(await readFile(path, 'utf8')) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+export async function writeRuntimeJson(
+  path: string,
+  value: unknown,
+): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    const handle = await open(temp, 'wx', 0o600);
+    try {
+      await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8');
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    await rename(temp, path);
+  } finally {
+    await rm(temp, { force: true }).catch(() => undefined);
+  }
+}
+
+export async function mutateRuntimeJson<T>(
+  path: string,
+  fallback: T,
+  mutate: (value: T) => T | Promise<T>,
+): Promise<T> {
+  return withRuntimeFileLock(path, async () => {
+    const next = await mutate(await readRuntimeJson(path, fallback));
+    await writeRuntimeJson(path, next);
+    return next;
+  });
+}
+
+export async function removeManagedPath(
+  path: string,
+  expectedRoot: string,
+): Promise<void> {
+  const target = resolve(path);
+  const root = resolve(expectedRoot);
+  const rel = target.slice(root.length);
+  if (target === root || !target.startsWith(`${root}/`) || rel.includes('\0')) {
+    throw new Error(`拒绝清理托管根目录之外的路径：${target}`);
+  }
+  await rm(target, { recursive: true, force: true });
+}
+
+export async function runtimeFileVersion(path: string): Promise<string> {
+  const info = await stat(path);
+  return `${info.dev}:${info.ino}:${info.size}:${info.mtimeMs}`;
+}
+
+const activeOutputs = new Set<string>();
+const OUTPUT_RETENTION_MS = 7 * 24 * 60 * 60_000;
+const OUTPUT_GLOBAL_LIMIT = 5 * 1024 * 1024 * 1024;
+let pruneOutputsPromise: Promise<void> | undefined;
+
+export function registerRuntimeOutput(path: string): void {
+  activeOutputs.add(resolve(path));
+}
+
+export function unregisterRuntimeOutput(path: string): void {
+  activeOutputs.delete(resolve(path));
+}
+
+export function pruneRuntimeOutputs(): Promise<void> {
+  pruneOutputsPromise ??= (async () => {
+    const root = join(agentStateDir(), 'runtime');
+    const files: Array<{ path: string; size: number; mtimeMs: number }> = [];
+    for (const workspace of await readdir(root).catch(() => [])) {
+      const workspaceDir = join(root, workspace);
+      for (const session of await readdir(workspaceDir).catch(() => [])) {
+        const outputDir = join(workspaceDir, session, 'outputs');
+        const sessionFiles: Array<{
+          path: string;
+          size: number;
+          mtimeMs: number;
+        }> = [];
+        for (const name of await readdir(outputDir).catch(() => [])) {
+          const path = join(outputDir, name);
+          const info = await stat(path).catch(() => undefined);
+          if (info?.isFile() && !activeOutputs.has(resolve(path))) {
+            sessionFiles.push({ path, size: info.size, mtimeMs: info.mtimeMs });
+          }
+        }
+        sessionFiles.sort((left, right) => right.mtimeMs - left.mtimeMs);
+        await Promise.all(
+          sessionFiles
+            .slice(50)
+            .map((file) =>
+              rm(file.path, { force: true }).catch(() => undefined),
+            ),
+        );
+        files.push(...sessionFiles.slice(0, 50));
+      }
+    }
+    files.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    let retainedBytes = 0;
+    const cutoff = Date.now() - OUTPUT_RETENTION_MS;
+    for (const file of files) {
+      retainedBytes += file.size;
+      if (file.mtimeMs < cutoff || retainedBytes > OUTPUT_GLOBAL_LIMIT) {
+        await rm(file.path, { force: true }).catch(() => undefined);
+      }
+    }
+  })().finally(() => {
+    pruneOutputsPromise = undefined;
+  });
+  return pruneOutputsPromise;
+}