dsh-taskboard 0.6.6 → 0.7.0

package/src/host/storage.ts

@@ -0,0 +1,212 @@
+/** Configurable taskboard data directory and crash-safe three-part migration. */
+import { randomUUID } from 'node:crypto'
+import { constants, copyFile, access, mkdir, open, readFile, readdir, rename, rm, stat } from 'node:fs/promises'
+import { existsSync, readFileSync } from 'node:fs'
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import type { StorageStatus, StorageMigrationResult } from '../shared/api.ts'
+import type { AssetStore } from './assets.ts'
+import type { TaskStore } from './store.ts'
+import type { TemplateStore } from './templates.ts'
+import { StorageQueue } from './storage-queue.ts'
+
+export const STORAGE_CONFIG_FILE = 'dsh-taskboard-storage.json'
+const CONFIG_SCHEMA_VERSION = 1
+
+type StorageConfig = { schemaVersion: number; dataDirectory: string }
+
+export interface StorageCoordinatorOptions {
+  defaultDirectory: string
+  configFile: string
+  ledgerName: string
+  templatesName: string
+  assetsName: string
+}
+
+function normalized(path: string): string {
+  const value = resolve(path.trim())
+  return process.platform === 'win32' ? value.toLowerCase() : value
+}
+
+function samePath(a: string, b: string): boolean { return normalized(a) === normalized(b) }
+
+function inside(parent: string, child: string): boolean {
+  const rel = relative(resolve(parent), resolve(child))
+  return rel.length === 0 || (!rel.startsWith('..') && !isAbsolute(rel))
+}
+
+async function exists(path: string): Promise<boolean> {
+  try { await stat(path); return true } catch { return false }
+}
+
+async function persistConfig(file: string, config: StorageConfig): Promise<void> {
+  await mkdir(dirname(file), { recursive: true })
+  const temp = join(dirname(file), `.${basename(file)}.${randomUUID()}.tmp`)
+  const handle = await open(temp, 'w')
+  try {
+    await handle.writeFile(JSON.stringify(config, null, 2), 'utf8')
+    await handle.sync()
+  } finally { await handle.close() }
+  await rename(temp, file)
+}
+
+function configuredDirectory(options: StorageCoordinatorOptions): { directory: string; configured: boolean; error?: string } {
+  if (!existsSync(options.configFile)) return { directory: resolve(options.defaultDirectory), configured: false }
+  try {
+    const parsed = JSON.parse(readFileSync(options.configFile, 'utf8')) as Partial<StorageConfig>
+    if (parsed.schemaVersion !== CONFIG_SCHEMA_VERSION || typeof parsed.dataDirectory !== 'string' || !isAbsolute(parsed.dataDirectory)) {
+      return { directory: resolve(options.defaultDirectory), configured: false, error: 'invalid storage location config; using the default directory' }
+    }
+    return { directory: resolve(parsed.dataDirectory), configured: true }
+  } catch (error) {
+    return { directory: resolve(options.defaultDirectory), configured: false, error: `cannot read storage location config: ${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+/** Coordinates all persistent stores so migration cannot race normal writes. */
+export class StorageCoordinator {
+  readonly queue = new StorageQueue()
+  private currentDirectory: string
+  private configured: boolean
+  private startupError?: string
+  private stores?: { ledger: TaskStore; templates: TemplateStore; assets: AssetStore }
+
+  constructor(private readonly options: StorageCoordinatorOptions) {
+    const selected = configuredDirectory(options)
+    this.currentDirectory = selected.directory
+    this.configured = selected.configured
+    if (selected.error !== undefined) console.warn(`[dsh-taskboard] ${selected.error}`)
+    if (selected.configured && !existsSync(selected.directory)) {
+      this.startupError = `configured storage directory is unavailable: ${selected.directory}`
+    }
+  }
+
+  attach(stores: { ledger: TaskStore; templates: TemplateStore; assets: AssetStore }): void { this.stores = stores }
+
+  directory(): string { return this.currentDirectory }
+  ledgerPath(directory = this.currentDirectory): string { return join(directory, this.options.ledgerName) }
+  templatesPath(directory = this.currentDirectory): string { return join(directory, this.options.templatesName) }
+  assetsPath(directory = this.currentDirectory): string { return join(directory, this.options.assetsName) }
+
+  async ready(): Promise<void> {
+    if (this.startupError !== undefined) throw new Error(`taskboard_storage_unavailable: ${this.startupError}`)
+    await mkdir(this.currentDirectory, { recursive: true })
+    await access(this.currentDirectory, constants.R_OK | constants.W_OK)
+  }
+
+  private requireStores(): { ledger: TaskStore; templates: TemplateStore; assets: AssetStore } {
+    if (this.stores === undefined) throw new Error('storage coordinator is not attached')
+    return this.stores
+  }
+
+  async status(): Promise<StorageStatus> {
+    let assetCount = 0
+    let assetBytes = 0
+    try {
+      for (const entry of await readdir(this.assetsPath(), { withFileTypes: true })) {
+        if (!entry.isFile()) continue
+        assetCount += 1
+        try { assetBytes += (await stat(join(this.assetsPath(), entry.name))).size } catch { /* best effort */ }
+      }
+    } catch { /* no attachment directory yet */ }
+    return {
+      currentDirectory: this.currentDirectory,
+      defaultDirectory: resolve(this.options.defaultDirectory),
+      isDefault: samePath(this.currentDirectory, this.options.defaultDirectory),
+      configured: this.configured,
+      writable: this.startupError === undefined,
+      assetCount,
+      assetBytes,
+      ...(this.startupError === undefined ? {} : { error: this.startupError }),
+    }
+  }
+
+  async check(directory: string): Promise<StorageStatus> {
+    const target = this.validateTarget(directory)
+    await mkdir(target, { recursive: true })
+    await this.assertTargetAvailable(target)
+    const probe = join(target, `.dsh-taskboard-write-${randomUUID()}.tmp`)
+    const handle = await open(probe, 'wx')
+    try { await handle.writeFile('ok', 'utf8'); await handle.sync() } finally { await handle.close(); await rm(probe, { force: true }) }
+    return { ...(await this.status()), checkedDirectory: target, writable: true }
+  }
+
+  private validateTarget(directory: string): string {
+    if (typeof directory !== 'string' || directory.trim().length === 0) return resolve(this.options.defaultDirectory)
+    if (!isAbsolute(directory.trim())) throw new Error('storage directory must be an absolute path')
+    const target = resolve(directory.trim())
+    if (inside(this.assetsPath(), target)) throw new Error('storage directory cannot be inside the current attachment directory')
+    return target
+  }
+
+  private async assertTargetAvailable(target: string): Promise<void> {
+    if (samePath(target, this.currentDirectory)) return
+    for (const path of [this.ledgerPath(target), this.templatesPath(target), this.assetsPath(target)]) {
+      if (await exists(path)) throw new Error(`target already contains ${basename(path)}`)
+    }
+  }
+
+  async migrate(directory: string): Promise<StorageMigrationResult> {
+    const target = this.validateTarget(directory)
+    return this.queue.run(async () => {
+      // Re-check only after acquiring the shared queue: another migration may
+      // have switched to this target while this request was waiting.
+      if (samePath(target, this.currentDirectory)) return { ...(await this.status()), migrated: false, warnings: [] }
+      if (this.startupError !== undefined) throw new Error(`taskboard_storage_unavailable: ${this.startupError}`)
+      const stores = this.requireStores()
+      await stores.ledger.load()
+      await mkdir(target, { recursive: true })
+      await this.assertTargetAvailable(target)
+
+      const oldDirectory = this.currentDirectory
+      const stage = join(target, `.dsh-taskboard-migration-${randomUUID()}`)
+      const stageLedger = this.ledgerPath(stage)
+      const stageTemplates = this.templatesPath(stage)
+      const stageAssets = this.assetsPath(stage)
+      const warnings: string[] = []
+      try {
+        await mkdir(stage, { recursive: true })
+        await stores.ledger.writeCopy(stageLedger)
+        await stores.templates.writeCopy(stageTemplates)
+        await mkdir(stageAssets, { recursive: true })
+        try {
+          for (const entry of await readdir(stores.assets.location(), { withFileTypes: true })) {
+            if (entry.isFile()) await copyFile(join(stores.assets.location(), entry.name), join(stageAssets, entry.name), constants.COPYFILE_EXCL)
+          }
+        } catch (error) {
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+        }
+        JSON.parse(await readFile(stageLedger, 'utf8'))
+        JSON.parse(await readFile(stageTemplates, 'utf8'))
+
+        await rename(stageLedger, this.ledgerPath(target))
+        await rename(stageTemplates, this.templatesPath(target))
+        await rename(stageAssets, this.assetsPath(target))
+        if (samePath(target, this.options.defaultDirectory)) await rm(this.options.configFile, { force: true })
+        else await persistConfig(this.options.configFile, { schemaVersion: CONFIG_SCHEMA_VERSION, dataDirectory: target })
+
+        stores.ledger.setLocation(this.ledgerPath(target))
+        stores.templates.setLocation(this.templatesPath(target))
+        stores.assets.setLocation(this.assetsPath(target))
+        this.currentDirectory = target
+        this.configured = !samePath(target, this.options.defaultDirectory)
+        this.startupError = undefined
+
+        for (const oldPath of [this.ledgerPath(oldDirectory), this.templatesPath(oldDirectory), this.assetsPath(oldDirectory)]) {
+          try { await rm(oldPath, { recursive: true, force: true }) } catch (error) { warnings.push(`could not remove ${oldPath}: ${error instanceof Error ? error.message : String(error)}`) }
+        }
+        await rm(stage, { recursive: true, force: true })
+        return { ...(await this.status()), migrated: true, warnings }
+      } catch (error) {
+        await rm(stage, { recursive: true, force: true }).catch(() => undefined)
+        // The pointer is the commit point. Before it changes, prepared target
+        // files are safe to remove and the old directory remains authoritative.
+        if (samePath(this.currentDirectory, oldDirectory)) {
+          for (const path of [this.ledgerPath(target), this.templatesPath(target), this.assetsPath(target)]) {
+            await rm(path, { recursive: true, force: true }).catch(() => undefined)
+          }
+        }
+        throw error
+      }
+    })
+  }
+}

package/src/host/store.ts

@@ -1,5 +1,5 @@
 /**
- * Host-side task ledger: one JSON file under the DSH home, mutated through a
+ * Host-side task ledger: one JSON file under the active data directory, mutated through a
  * serial write queue, published as immutable snapshots with a global
  * monotonic revision. Change subscribers (P2: SSE route) observe every
  * committed mutation.
@@ -17,6 +17,7 @@ import {
   type TaskLedger,
   type TaskRecord,
 } from '../shared/protocol.ts'
+import type { StorageQueue } from './storage-queue.ts'
 
 /** One committed ledger mutation, handed to change subscribers. */
 export interface LedgerChange {
@@ -32,6 +33,8 @@ export interface LedgerChange {
 export interface TaskStoreOptions {
   /** Absolute ledger file path. */
   file: string
+  /** Optional queue shared with templates/assets and storage migration. */
+  queue?: StorageQueue
 }
 
 /**
@@ -40,20 +43,42 @@ export interface TaskStoreOptions {
  * atomically (temp file + rename), and only then notifies subscribers.
  */
 export class TaskStore {
-  private readonly file: string
+  private file: string
+  private readonly storageQueue?: StorageQueue
   private ledger: TaskLedger = emptyLedger()
   private readonly subscribers = new Set<(change: LedgerChange) => void>()
   private queue: Promise<unknown> = Promise.resolve()
   private loaded = false
+  private loadPromise: Promise<void> | undefined
 
   /** @param options - file location. */
   constructor(options: TaskStoreOptions) {
     this.file = options.file
+    this.storageQueue = options.queue
   }
 
+  /** Current absolute ledger path. */
+  location(): string { return this.file }
+
+  /** Persist the live in-memory ledger to another file without switching. */
+  async writeCopy(file: string): Promise<void> {
+    await this.load()
+    await persistAtomic(file, JSON.stringify(this.ledger))
+  }
+
+  /** Switch future writes after a prepared migration commits. */
+  setLocation(file: string): void { this.file = file }
+
   /** Load (once) from disk; a missing file starts empty; a corrupt file is quarantined, not thrown. */
-  async load(): Promise<void> {
-    if (this.loaded) return
+  load(): Promise<void> {
+    if (this.loaded) return Promise.resolve()
+    if (this.loadPromise !== undefined) return this.loadPromise
+    this.loadPromise = this.loadOnce()
+    return this.loadPromise
+  }
+
+  /** Perform the single physical ledger read shared by all startup callers. */
+  private async loadOnce(): Promise<void> {
     try {
       const raw = await readFile(this.file, 'utf8')
       const parsed = JSON.parse(raw) as TaskLedger
@@ -138,10 +163,13 @@ export class TaskStore {
    * @returns the backup file path.
    */
   async backup(): Promise<string> {
-    await this.load()
-    const target = `${this.file}.backup-${Date.now()}`
-    await persistAtomic(target, JSON.stringify(this.ledger, null, 2))
-    return target
+    const run = async (): Promise<string> => {
+      await this.load()
+      const target = `${this.file}.backup-${Date.now()}`
+      await persistAtomic(target, JSON.stringify(this.ledger, null, 2))
+      return target
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
   }
 
   /**
@@ -183,8 +211,8 @@ export class TaskStore {
         changed: changed.map(t => deepFreeze(structuredClone(t))),
       }
     }
-    const result = (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>
-    return result
+    if (this.storageQueue !== undefined) return this.storageQueue.run(run)
+    return (this.queue = this.queue.then(run, run)) as ReturnType<typeof run>
   }
 
   /**
@@ -198,8 +226,8 @@ export class TaskStore {
       await this.load()
       return fn(deepFreeze(structuredClone(this.ledger)))
     }
-    const result = (this.queue = this.queue.then(run, run)) as Promise<T>
-    return result
+    if (this.storageQueue !== undefined) return this.storageQueue.run(run)
+    return (this.queue = this.queue.then(run, run)) as Promise<T>
   }
 }
 

package/src/host/templates.ts

@@ -10,66 +10,16 @@
  */
 import { readFile } from 'node:fs/promises'
 import type { TaskTemplate } from '../shared/api.ts'
+import { BUILTIN_TEMPLATE_CONTENT, BUILTIN_TEMPLATE_IDS, type BuiltinTemplateId } from '../shared/builtin-templates.ts'
+import type { StorageQueue } from './storage-queue.ts'
 
-/** The built-in templates seeded when the side file does not exist yet. */
-export const BUILTIN_TEMPLATES: ReadonlyArray<{ id: string; name: string; task: TaskTemplate['task'] }> = [
-  {
-    id: 'tpl-feature',
-    name: '新增功能',
-    task: {
-      title: '新增：',
-      prompt: [
-        '实现以上新功能并按序交接：',
-        '1. 明确需求边界与验收标准，列出实现要点',
-        '2. 实现功能（含类型定义与错误处理）',
-        '3. 补充测试（单测/回归）',
-        '4. 运行相关测试套件确认通过',
-      ].join('\n'),
-      urgency: 'normal',
-      checklist: ['实现要点已明确（需求边界与验收标准）', '功能已实现并补充测试', '相关测试套件通过'],
-    },
-  },
-  {
-    id: 'tpl-bugfix',
-    name: 'Bug 修复',
-    task: {
-      title: '修复：',
-      prompt: [
-        '修复以上问题并按序交接：',
-        '1. 复现问题（写最小复现步骤或测试）',
-        '2. 定位根因，说明为什么会发生',
-        '3. 修复并补回归测试',
-        '4. 运行相关测试套件确认无回归',
-      ].join('\n'),
-      urgency: 'urgent',
-      checklist: ['已复现并定位根因', '修复已提交到任务分支', '回归测试通过'],
-    },
-  },
-  {
-    id: 'tpl-release',
-    name: '发布检查',
-    task: {
-      title: '发布：',
-      prompt: '执行发布流程：版本号更新、构建、测试、变更记录，完成后按序交接（不要实际推送/发布，等用户确认）。',
-      urgency: 'normal',
-      checklist: ['版本号已更新（package.json 与版本常量同步）', '构建通过', '全部测试通过', '变更记录已写'],
-    },
-  },
-  {
-    id: 'tpl-patrol',
-    name: '例行巡检',
-    task: {
-      title: '巡检：',
-      prompt: [
-        '例行巡检：检查依赖更新、失败测试、明显代码问题与未处理的告警。',
-        '发现的问题逐条列出（严重度/位置/建议），小问题直接修复，大问题只报告不动手。',
-        '输出巡检摘要（用 {{lastComments}} 可回看上次巡检结论）。',
-      ].join('\n'),
-      urgency: 'relaxed',
-      execution: { mode: 'scheduled', cron: '0 9 * * 1' },
-    },
-  },
-]
+/**
+ * The built-in templates seeded when the side file does not exist yet.
+ * Seeded from the shared zh content (the side file is plain data; the client
+ * resolves the active locale at render time — see shared/builtin-templates.ts).
+ */
+export const BUILTIN_TEMPLATES: ReadonlyArray<{ id: BuiltinTemplateId; name: string; task: TaskTemplate['task'] }> =
+  BUILTIN_TEMPLATE_IDS.map(id => ({ id, name: BUILTIN_TEMPLATE_CONTENT.zh[id].name, task: BUILTIN_TEMPLATE_CONTENT.zh[id].task }))
 
 /** Mint a template id. */
 function newTemplateId(): string {
@@ -83,9 +33,22 @@ function newTemplateId(): string {
 export class TemplateStore {
   private templates: TaskTemplate[] | undefined
   private loaded = false
+  private file: string
 
   /** @param file - absolute side-file path (next to the ledger). */
-  constructor(private readonly file: string) {}
+  constructor(file: string, private readonly storageQueue?: StorageQueue) { this.file = file }
+
+  /** Current absolute template-file path. */
+  location(): string { return this.file }
+
+  /** Persist the loaded template set to another file without switching. */
+  async writeCopy(file: string): Promise<void> {
+    await this.ensure()
+    await this.persist(this.templates ?? [], file)
+  }
+
+  /** Switch future writes after a prepared migration commits. */
+  setLocation(file: string): void { this.file = file }
 
   /** Load once; a missing file seeds the built-ins; a corrupt file resets. */
   private async ensure(): Promise<void> {
@@ -110,11 +73,11 @@ export class TemplateStore {
   }
 
   /** Atomic persist (temp + fsync + rename — S10, same discipline as the ledger). */
-  private async persist(templates: TaskTemplate[]): Promise<void> {
+  private async persist(templates: TaskTemplate[], file = this.file): Promise<void> {
     const { mkdir, open, rename } = await import('node:fs/promises')
     const { dirname, join } = await import('node:path')
-    await mkdir(dirname(this.file), { recursive: true })
-    const temp = join(dirname(this.file), `.${Math.random().toString(36).slice(2)}.tmp`)
+    await mkdir(dirname(file), { recursive: true })
+    const temp = join(dirname(file), `.${Math.random().toString(36).slice(2)}.tmp`)
     const fh = await open(temp, 'w')
     try {
       await fh.writeFile(JSON.stringify({ templates }, null, 2), 'utf8')
@@ -122,13 +85,16 @@ export class TemplateStore {
     } finally {
       await fh.close()
     }
-    await rename(temp, this.file)
+    await rename(temp, file)
   }
 
   /** All templates (oldest first). */
   async list(): Promise<TaskTemplate[]> {
-    await this.ensure()
-    return (this.templates ?? []).slice()
+    const run = async (): Promise<TaskTemplate[]> => {
+      await this.ensure()
+      return (this.templates ?? []).slice()
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
   }
 
   /**
@@ -136,6 +102,7 @@ export class TemplateStore {
    * @returns the stored template.
    */
   async upsert(input: { id?: string; name: string; task: TaskTemplate['task'] }): Promise<TaskTemplate> {
+    const run = async (): Promise<TaskTemplate> => {
     await this.ensure()
     const templates = this.templates ?? []
     const name = input.name.trim()
@@ -153,10 +120,13 @@ export class TemplateStore {
     else templates.push(stored)
     await this.persist(templates)
     return stored
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
   }
 
   /** Delete a template by id; returns whether it existed. */
   async remove(id: string): Promise<boolean> {
+    const run = async (): Promise<boolean> => {
     await this.ensure()
     const templates = this.templates ?? []
     const index = templates.findIndex(t => t.id === id)
@@ -164,5 +134,7 @@ export class TemplateStore {
     templates.splice(index, 1)
     await this.persist(templates)
     return true
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
   }
 }

package/src/host/tools.ts

@@ -1,3 +1,5 @@
+import type { SessionArchiveResult } from '../shared/api.ts'
+import { archiveTaskSessions } from './archive-sessions.ts'
 /**
  * The ten `taskboard_*` agent tools. All writes require a calling agent
  * session (ownership audit), carry optimistic-version checks, and enforce
@@ -136,6 +138,7 @@ function taskDetail(t: TaskRecord & { effectivePrompt?: string }): string {
 
 /** Stable error codes surfaced at the head of tool error messages. */
 export const ERR = {
+  notReady: 'taskboard_not_ready',
   notFound: 'not_found',
   versionConflict: 'version_conflict',
   workspaceMismatch: 'workspace_mismatch',
@@ -162,6 +165,8 @@ export interface WorkspaceFace {
   get(id: string): { id: string; path: string; title: string } | undefined
   /** List all workspaces. */
   list(): Array<{ id: string; path: string; title: string }>
+  /** Archive one session durably (when supported by runtime workspaceRegistry). */
+  archiveSession?(sessionId: string): Promise<void>
 }
 
 /** Adapt the real registry to the narrow face. */
@@ -178,6 +183,9 @@ export function workspaceFace(registry: WorkspaceRegistry): WorkspaceFace {
       return ws === undefined ? undefined : { id: ws.id, path: ws.path, title: ws.title }
     },
     list: () => registry.list().map(ws => ({ id: ws.id, path: ws.path, title: ws.title })),
+    ...(typeof registry.archiveSession === 'function'
+      ? { archiveSession: (sessionId: string) => registry.archiveSession(sessionId as Parameters<WorkspaceRegistry['archiveSession']>[0]) }
+      : {}),
   }
 }
 
@@ -187,6 +195,8 @@ export interface ToolDeps {
   workspaces: WorkspaceFace
   /** Current epoch ms (injectable for tests). */
   now: () => number
+  /** Shared startup barrier; tool definitions stay registered while services initialize. */
+  ready?: () => Promise<void>
   /**
    * Registered model provider routes (from the host llm runtime), for
    * advisory validation of pinned models; undefined = runtime unavailable,
@@ -281,16 +291,17 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
 
   // Env-gated tool-call tracing (ATB_TRACE=1) — evidence for protocol E2E.
   const register = (tool: { name: string; execute?: unknown }) => {
-    if (process.env.ATB_TRACE === '1' && typeof tool.execute === 'function') {
+    if (typeof tool.execute === 'function') {
       const orig = tool.execute as (args: unknown, exec: unknown) => Promise<unknown>
       tool.execute = async (args: unknown, exec: unknown) => {
-        console.error(`[atb ▶] ${tool.name}`, JSON.stringify(args).slice(0, 300))
+        await deps.ready?.()
+        if (process.env.ATB_TRACE === '1') console.error(`[atb ▶] ${tool.name}`, JSON.stringify(args).slice(0, 300))
         try {
           const result = await orig(args, exec)
-          console.error(`[atb ✓] ${tool.name}`, JSON.stringify(result).slice(0, 300))
+          if (process.env.ATB_TRACE === '1') console.error(`[atb ✓] ${tool.name}`, JSON.stringify(result).slice(0, 300))
           return result
         } catch (error) {
-          console.error(`[atb ✗] ${tool.name}`, String(error).slice(0, 400))
+          if (process.env.ATB_TRACE === '1') console.error(`[atb ✗] ${tool.name}`, String(error).slice(0, 400))
           throw error
         }
       }
@@ -411,7 +422,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     output: {
       schema: JSON_OUT,
       render: (_args, value) => {
-        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const v = value as { task?: { id?: string; status?: string; version?: number }; sessionArchive?: SessionArchiveResult }
         const t = v.task
         return [{ type: 'text', text: t === undefined ? '创建失败。' : `已创建任务 ${t.id} [${t.status}] v${t.version}。写入前先 taskboard_get 读取。` }]
       },
@@ -501,7 +512,7 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
     output: {
       schema: JSON_OUT,
       render: (_args, value) => {
-        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const v = value as { task?: { id?: string; status?: string; version?: number }; sessionArchive?: SessionArchiveResult }
         const t = v.task
         return [{ type: 'text', text: t === undefined ? '更新失败。' : `已更新任务 ${t.id}，当前 v${t.version} [${t.status}]。` }]
       },
@@ -554,16 +565,17 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
       id: { type: 'string', required: true, description: 'Task id.' },
       status: { type: 'string', required: true, description: 'Target status.' },
       ifVersion: { type: 'number', required: true, description: 'Task version you read; fails on mismatch.' },
+      archiveSessions: { type: 'boolean', description: 'When moving to archived: whether to archive associated execution sessions as well. Defaults to false.' },
     },
     output: {
       schema: JSON_OUT,
       render: (_args, value) => {
-        const v = value as { task?: { id?: string; status?: string; version?: number } }
+        const v = value as { task?: { id?: string; status?: string; version?: number }; sessionArchive?: SessionArchiveResult }
         const t = v.task
-        return [{ type: 'text', text: t === undefined ? '移动失败。' : `任务 ${t.id} 已移到 ${t.status}，当前 v${t.version}。` }]
+        return [{ type: 'text', text: t === undefined ? '移动失败。' : `任务 ${t.id} 已移到 ${t.status}，当前 v${t.version}。${v.sessionArchive === undefined ? '' : ` 会话归档结果：${JSON.stringify(v.sessionArchive)}`}` }]
       },
     },
-    async execute(args: { id: string; status: string; ifVersion: number }, exec: unknown) {
+    async execute(args: { id: string; status: string; ifVersion: number; archiveSessions?: boolean }, exec: unknown) {
       try {
         const { actor } = caller(exec as ToolRunContext)
         const to = asStatus(args.status)
@@ -575,9 +587,11 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           : undefined
         // R1: every state guard + the write itself run inside the mutation.
         let next: TaskRecord | undefined
+        let beforeTask: TaskRecord | undefined
         await store.mutate('task-moved', ledger => {
           const { index, task } = liveTaskAt(ledger, args.id)
           versionGuard(task, args.ifVersion)
+          beforeTask = task
 
           // Code-level gate: agents never complete a task.
           if (to === 'done') {
@@ -607,7 +621,10 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
           ledger.tasks[index] = next
           return [next]
         })
-        return json({ task: summarize(next!) })
+        const sessionArchive = to === 'archived' && args.archiveSessions === true
+          ? await archiveTaskSessions(beforeTask ?? next!, deps.workspaces.archiveSession)
+          : undefined
+        return json({ task: summarize(next!), ...(sessionArchive !== undefined ? { sessionArchive } : {}) })
       } catch (error) { fail(error) }
     },
   })) as () => void)
@@ -929,4 +946,4 @@ export function registerTaskboardTools(ctx: ToolContextFace, deps: ToolDeps): Ar
   })) as () => void)
 
   return disposers
-}
+}