dsh-taskboard 0.6.7 → 0.7.1

package/src/client/controller.ts

@@ -8,7 +8,7 @@ import type { SessionArchiveResult } from '../shared/api.ts'
  *
  * @module dsh-taskboard/client/controller
  */
-import type { ChangeEvent, DiagnosticsResponse, DiffResponse, ImportCommitResponse, ImportPreviewResponse, MergeRepoResult, PromptCompletionsResponse, TaskTemplate, TaskTemplateSpec, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
+import type { AttachmentUpload, ChangeEvent, DiagnosticsResponse, DiffResponse, ImportCommitResponse, ImportPreviewResponse, MergeRepoResult, PromptCompletionsResponse, StorageStatus, TaskTemplate, TaskTemplateSpec, UpdateTaskBody, WorkspaceView } from '../shared/api.ts'
 import type { ChecklistItem, TaskLedger, TaskRecord, Urgency } from '../shared/protocol.ts'
 import { emptyLedger } from '../shared/protocol.ts'
 import type { TaskboardClient } from './api.ts'
@@ -78,6 +78,10 @@ export interface ControllerState {
   importOpen: boolean
   /** Board-settings modal visible (0.5.0). */
   settingsOpen: boolean
+  /** Current durable-data directory, loaded when settings opens. */
+  storage?: StorageStatus
+  /** Settled migration outcome (0.7.0): success path plus non-fatal warnings. */
+  storageNotice?: { path: string; warnings: string[] }
   /** Fields a chosen template prefills into the create form (consumed on open). */
   templatePrefill?: TaskTemplateSpec
   /** Transient error surface (action failures); cleared on next success. */
@@ -524,6 +528,16 @@ export class BoardController {
     }
   }
 
+  /** Upload an image without putting its bytes in the ledger or agent context. */
+  async uploadImage(file: Blob): Promise<AttachmentUpload | undefined> {
+    try {
+      return await this.client.uploadImage(file)
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+      return undefined
+    }
+  }
+
   /** Trigger a manual run (fresh in-project session, pinned model); `reuse` = 续跑. */
   async run(id: string, reuse = false): Promise<void> {
     try {
@@ -587,10 +601,15 @@ export class BoardController {
   closeDiagnostics(): void { this.setState({ diagOpen: false }) }
 
   /** Open the board-settings modal (0.5.0). */
-  openSettings(): void { this.setState({ settingsOpen: true }) }
+  openSettings(): void {
+    this.setState({ settingsOpen: true })
+    void this.client.storage()
+      .then(storage => this.setState({ storage, error: undefined }))
+      .catch(error => this.setState({ error: error instanceof Error ? error.message : String(error) }))
+  }
 
   /** Close the board-settings modal. */
-  closeSettings(): void { this.setState({ settingsOpen: false }) }
+  closeSettings(): void { this.setState({ settingsOpen: false, storageNotice: undefined }) }
 
   /**
    * Replace board settings (0.5.0). The host broadcasts a settings-updated
@@ -608,6 +627,38 @@ export class BoardController {
     }
   }
 
+  /** Validate a candidate host directory without changing the active store. */
+  async checkStorage(directory: string): Promise<boolean> {
+    try {
+      const storage = await this.client.checkStorage(directory)
+      this.setState({ storage, error: undefined })
+      return true
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+      return false
+    }
+  }
+
+  /** Atomically migrate all three stores and refresh the displayed location. */
+  async migrateStorage(directory: string): Promise<boolean> {
+    try {
+      const storage = await this.client.migrateStorage(directory)
+      // Success is surfaced as a dedicated notice (not the error banner);
+      // cleanup warnings render beneath it as warnings, never as errors.
+      this.setState({ storage, storageNotice: { path: storage.currentDirectory, warnings: storage.warnings }, error: undefined })
+      await this.refresh()
+      return true
+    } catch (error) {
+      this.setState({ error: error instanceof Error ? error.message : String(error) })
+      return false
+    }
+  }
+
+  /** Clear the settled migration notice (next user edit in the storage section). */
+  dismissStorageNotice(): void {
+    if (this.state.storageNotice !== undefined) this.setState({ storageNotice: undefined })
+  }
+
   /** Clean one orphan worktree (⚙ panel); refreshes the diagnostics payload. */
   async cleanupOrphan(workspaceId: string, taskId: string): Promise<void> {
     try {

package/src/client/i18n/en.ts

@@ -339,14 +339,14 @@ export const en: TaskboardDict = {
   'tpl.use.button': 'Use',
   'tpl.delete.title': 'Delete this template',
   'tpl.renamed': 'Template renamed',
-  'tpl.foot.hint': 'Templates are stored with the ledger in the DSH home directory and survive upgrades',
+  'tpl.foot.hint': 'Templates are stored with the ledger in the active data directory and survive upgrades',
 
   // ── import modal (ImportModal) ────────────────────────────────────
   'imp.aria': 'Import ledger',
   'imp.title': 'Import ledger',
   'imp.subtitle': 'Pick an exported JSON backup: preview first, then merge or replace everything',
   'imp.parseError': 'The file is not valid JSON',
-  'imp.note': 'The ⬇ JSON export is a same-format backup and can be imported to restore; the file\u2019s schemaVersion must match the current version.',
+  'imp.note': 'The ⬇ JSON export restores the ledger. Back up the dsh-taskboard-assets folder in the data directory shown in Settings as well. The file\u2019s schemaVersion must match the current version.',
   'imp.previewing': 'Previewing…',
   'imp.stat.create': 'New',
   'imp.stat.overwrite': 'Overwrite (same id)',
@@ -370,7 +370,7 @@ export const en: TaskboardDict = {
   // ── board settings modal (SettingsModal) ──────────────────────────
   'set.aria': 'Board settings',
   'set.title': 'Board settings',
-  'set.subtitle': 'Global defaults for new tasks and session sync',
+  'set.subtitle': 'New-task defaults, session sync, and local data storage',
   'set.iso.heading': 'Default execution isolation',
   'set.iso.noneHint': 'No git; works directly in the project directory (factory default)',
   'set.iso.worktreeHint': 'Each execution runs on its own worktree branch (task/title+ID), isolated from the others; multi-repo workspaces are mirrored whole (one branch per repo)',
@@ -387,6 +387,18 @@ export const en: TaskboardDict = {
   'set.foot.dirty': 'Unsaved changes',
   'set.foot.clean': 'Matches the current board settings',
   'set.action.save': 'Save settings',
+  'set.storage.heading': 'Data storage location',
+  'set.storage.hint': 'The task ledger, templates, and image attachments live together in this directory. Changing it copies and verifies everything before switching.',
+  'set.storage.loading': 'Loading the current path…',
+  'set.storage.current': 'Current path: {path}',
+  'set.storage.assets': 'Image attachments: {count}, {size} MiB',
+  'set.storage.default': 'Restore default path',
+  'set.storage.check': 'Check path',
+  'set.storage.migrate': 'Migrate data',
+  'set.storage.migrating': 'Migrating…',
+  'set.storage.confirm': 'Migrate the complete task ledger, templates, and image attachments?\n\nFrom: {from}\nTo: {to}\n\nWrites queue briefly during migration.',
+  'set.storage.migrated': 'Migration succeeded — data now lives in {path}',
+  'set.storage.warnings': 'Migration finished, but some old files could not be removed: {warnings}',
 
   // ── execution permission (PR #14) ─────────────────────────────────
   'form.field.permission': 'Execution permission',
@@ -420,6 +432,10 @@ export const en: TaskboardDict = {
   'md.imageTitle': 'Click to view full size ({alt})',
   'md.lightboxAlt': 'Full-size preview',
   'md.closePreview': 'Close preview',
+  'image.add': 'Insert image',
+  'image.uploading': 'Uploading…',
+  'image.hint': 'Choose, paste, or drop PNG/JPEG/GIF/WebP images up to 5 MB each',
+  'image.defaultAlt': 'Image',
 
   // ── slash completion popup (PR #14) ───────────────────────────────
   'slash.aria': 'Quick commands and skills',

package/src/client/i18n/zh.ts

@@ -341,14 +341,14 @@ export const zh = {
   'tpl.use.button': '用此新建',
   'tpl.delete.title': '删除该模板',
   'tpl.renamed': '模板已改名',
-  'tpl.foot.hint': '模板随台账一同保存在 DSH 主目录，升级不丢',
+  'tpl.foot.hint': '模板随台账一同保存在当前数据目录，升级不丢',
 
   // ── import modal (ImportModal) ────────────────────────────────────
   'imp.aria': '导入台账',
   'imp.title': '导入台账',
   'imp.subtitle': '选择导出的 JSON 备份文件：先预览、再合并或整册替换',
   'imp.parseError': '文件不是合法 JSON',
-  'imp.note': '⬇ JSON 导出的文件即为同格式备份，可直接导入恢复；导入文件的 schemaVersion 必须与当前版本一致。',
+  'imp.note': '⬇ JSON 导出可恢复台账；图片附件需同时备份设置页所示数据目录下的 dsh-taskboard-assets 文件夹。导入文件的 schemaVersion 必须与当前版本一致。',
   'imp.previewing': '预览中…',
   'imp.stat.create': '新增',
   'imp.stat.overwrite': '覆盖（同 id）',
@@ -372,7 +372,7 @@ export const zh = {
   // ── board settings modal (SettingsModal) ──────────────────────────
   'set.aria': '看板设置',
   'set.title': '看板设置',
-  'set.subtitle': '新建任务与会话同步的全局默认值',
+  'set.subtitle': '新建任务、会话同步与本地数据存储',
   'set.iso.heading': '默认执行隔离',
   'set.iso.noneHint': '不使用 git，直接在项目目录工作（出厂默认）',
   'set.iso.worktreeHint': '每次执行在独立 worktree 分支上进行（task/标题+ID），互不污染；多仓库工作区自动整区镜像（每仓库独立分支）',
@@ -389,6 +389,18 @@ export const zh = {
   'set.foot.dirty': '有未保存的修改',
   'set.foot.clean': '与看板当前设置一致',
   'set.action.save': '保存设置',
+  'set.storage.heading': '数据存储位置',
+  'set.storage.hint': '任务台账、模板和图片附件统一存放在此目录。修改路径会先完整复制并校验，再切换到新位置。',
+  'set.storage.loading': '正在读取当前路径…',
+  'set.storage.current': '当前路径：{path}',
+  'set.storage.assets': '图片附件：{count} 个，{size} MiB',
+  'set.storage.default': '恢复默认路径',
+  'set.storage.check': '检查路径',
+  'set.storage.migrate': '迁移数据',
+  'set.storage.migrating': '迁移中…',
+  'set.storage.confirm': '确认迁移全部任务台账、模板和图片附件？\n\n原路径：{from}\n新路径：{to}\n\n迁移期间写操作会短暂排队。',
+  'set.storage.migrated': '迁移成功，数据已迁移到 {path}',
+  'set.storage.warnings': '迁移完成，但部分旧数据未能清理：{warnings}',
 
   // ── execution permission (PR #14) ─────────────────────────────────
   'form.field.permission': '执行权限',
@@ -422,6 +434,10 @@ export const zh = {
   'md.imageTitle': '点击查看大图 ({alt})',
   'md.lightboxAlt': '大图预览',
   'md.closePreview': '关闭预览',
+  'image.add': '插入图片',
+  'image.uploading': '正在上传…',
+  'image.hint': '支持选择、粘贴或拖入 PNG/JPEG/GIF/WebP，单张不超过 5 MB',
+  'image.defaultAlt': '图片',
 
   // ── slash completion popup (PR #14) ───────────────────────────────
   'slash.aria': '快捷命令与技能',

package/src/client/image-insert.ts

@@ -0,0 +1,29 @@
+import type { AttachmentUpload } from '../shared/api.ts'
+
+export const IMAGE_ACCEPT = 'image/png,image/jpeg,image/gif,image/webp'
+const TYPES = new Set(IMAGE_ACCEPT.split(','))
+
+/** Keep Markdown alt text single-line and unable to close its own bracket. */
+export function imageAlt(fileName: string, fallback: string): string {
+  const withoutExtension = fileName.replace(/\.(?:png|jpe?g|gif|webp)$/i, '')
+  const clean = withoutExtension.replace(/[\[\]\r\n]/g, ' ').replace(/\s+/g, ' ').trim()
+  return clean.length > 0 ? clean.slice(0, 120) : fallback
+}
+
+export function imageMarkdown(asset: AttachmentUpload, alt: string): string {
+  return `![${alt}](${asset.url})`
+}
+
+/** Insert a block at the current selection, preserving readable line boundaries. */
+export function insertImageMarkdown(value: string, start: number, end: number, markdown: string): { value: string; cursor: number } {
+  const before = value.slice(0, start)
+  const after = value.slice(end)
+  const prefix = before.length > 0 && !before.endsWith('\n') ? '\n' : ''
+  const suffix = after.length > 0 && !after.startsWith('\n') ? '\n' : ''
+  const inserted = `${prefix}${markdown}${suffix}`
+  return { value: before + inserted + after, cursor: before.length + inserted.length }
+}
+
+export function acceptedImageFiles(files: Iterable<File>): File[] {
+  return Array.from(files).filter(file => TYPES.has(file.type)).slice(0, 10)
+}

package/src/client/styles.ts

@@ -398,6 +398,27 @@ button.dsh-atb-chip2.dsh-atb-chip-btn:hover {
 .dsh-atb-bubble-meta span { font-size: 10.5px; color: var(--dsw-text-secondary, gray); }
 .dsh-atb-bubble-body { font-size: 12.5px; line-height: 1.55; white-space: pre-wrap; word-break: break-word; }
 
+.dsh-atb-markdown-body { white-space: pre-wrap; word-break: break-word; }
+.dsh-atb-detail-img-wrap {
+  display: inline-flex; flex-direction: column; gap: 4px; max-width: min(100%, 520px); margin: 6px 8px 6px 0;
+  vertical-align: top;
+}
+.dsh-atb-detail-img {
+  display: block; max-width: 100%; max-height: 320px; object-fit: contain; border-radius: 8px; cursor: zoom-in;
+  border: 1px solid var(--dsw-border, rgba(128,128,128,.22)); background: var(--dsw-bg-inset, rgba(128,128,128,.08));
+}
+.dsh-atb-detail-img-caption { font-size: 10.5px; color: var(--dsw-text-secondary, gray); overflow-wrap: anywhere; }
+.dsh-atb-lightbox-backdrop {
+  position: fixed; inset: 0; z-index: 120; display: grid; place-items: center; padding: 28px;
+  background: rgba(0,0,0,.76); backdrop-filter: blur(3px);
+}
+.dsh-atb-lightbox-content { position: relative; max-width: 96vw; max-height: 92vh; }
+.dsh-atb-lightbox-img { display: block; max-width: 96vw; max-height: 92vh; object-fit: contain; border-radius: 10px; }
+.dsh-atb-lightbox-close {
+  position: absolute; top: -14px; right: -14px; width: 30px; height: 30px; border-radius: 999px; cursor: pointer;
+  border: 1px solid rgba(255,255,255,.38); background: rgba(20,20,20,.9); color: #fff;
+}
+
 .dsh-atb-composer { display: flex; gap: 7px; align-items: flex-end; margin-top: 2px; }
 .dsh-atb-composer-input {
   flex: 1; font: inherit; font-size: 12.5px; line-height: 1.5; padding: 7px 10px; border-radius: 9px;
@@ -410,6 +431,14 @@ button.dsh-atb-chip2.dsh-atb-chip-btn:hover {
   border: 1px solid transparent; background: var(--dsw-alias-button-primary-fill, var(--dsw-alias-brand-primary, #1f2328)); color: var(--dsw-alias-label-primary-foreground, #fff);
 }
 .dsh-atb-composer-send:disabled { opacity: .4; cursor: default; }
+.dsh-atb-image-actions { display: flex; align-items: center; gap: 8px; padding: 5px 1px 0; }
+.dsh-atb-image-add {
+  flex: none; font: inherit; font-size: 11.5px; line-height: 1.4; padding: 4px 8px; border-radius: 7px; cursor: pointer;
+  border: 1px solid var(--dsw-border, rgba(128,128,128,.3)); background: var(--dsw-bg-elevated, rgba(128,128,128,.08)); color: inherit;
+}
+.dsh-atb-image-add:hover:not(:disabled) { background: var(--dsw-bg-hover, rgba(128,128,128,.14)); }
+.dsh-atb-image-add:disabled { opacity: .45; cursor: default; }
+.dsh-atb-image-hint { font-size: 10.5px; color: var(--dsw-text-secondary, gray); }
 
 .dsh-atb-execlist { display: flex; flex-direction: column; gap: 5px; }
 .dsh-atb-exec-row {
@@ -854,9 +883,16 @@ color: var(--dsw-alias-state-business-primary, #3e63dd);
 .dsh-atb-imp-result { font-size: 12px; color: var(--dsw-alias-state-success-primary, #30a46c); margin-top: 10px; }
 .dsh-atb-badge[data-kind="checklist"] { color: var(--dsw-alias-label-secondary, inherit); }
 /* ---------- 0.5.0 board settings ---------- */
-.dsh-atb-set { max-width: 460px; width: min(460px, 92vw); }
+.dsh-atb-set { max-width: 620px; width: min(620px, 92vw); }
 .dsh-atb-set .dsh-atb-mode-picker { margin-top: 8px; }
 .dsh-atb-set .dsh-atb-isolation-note { margin-top: 10px; }
+.dsh-atb-storage-path { width: 100%; margin-top: 10px; font-family: ui-monospace, SFMono-Regular, Consolas, monospace; }
+.dsh-atb-storage-meta { display: grid; gap: 4px; margin-top: 8px; color: var(--dsh-atb-muted); font-size: 12px; overflow-wrap: anywhere; }
+.dsh-atb-storage-error { color: var(--dsh-atb-danger); }
+.dsh-atb-storage-actions { display: flex; flex-wrap: wrap; justify-content: flex-end; gap: 8px; margin-top: 10px; }
+.dsh-atb-storage-notice { display: grid; gap: 4px; margin-top: 8px; font-size: 12px; }
+.dsh-atb-storage-notice-ok { color: var(--dsw-alias-state-success-primary, #2e7d32); padding: 4px 8px; border-radius: 6px; background: rgba(46,125,50,.1); }
+.dsh-atb-storage-notice-warn { color: var(--dsw-alias-state-warning-primary, #b8860b); padding: 4px 8px; border-radius: 6px; background: rgba(184,134,11,.1); word-break: break-word; }
 
 /* ---------- 0.5.5 SlashPromptInput & Permission Picker ---------- */
 .dsh-atb-perm-picker { display: grid; grid-template-columns: repeat(3, 1fr); gap: 7px; margin-top: 4px; }

package/src/host/assets.ts

@@ -0,0 +1,120 @@
+/** Durable, content-addressed image attachments for task descriptions/comments. */
+import { createHash } from 'node:crypto'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { StorageQueue } from './storage-queue.ts'
+
+export const MAX_ASSET_BYTES = 5 * 1024 * 1024
+export const MAX_ASSET_STORE_BYTES = 200 * 1024 * 1024
+export const ORPHAN_GRACE_MS = 24 * 60 * 60 * 1000
+
+export type ImageKind = { extension: 'png' | 'jpg' | 'gif' | 'webp'; mime: 'image/png' | 'image/jpeg' | 'image/gif' | 'image/webp' }
+export type StoredAsset = ImageKind & { id: string; name: string; size: number; url: string }
+
+const ASSET_NAME_RE = /^([a-f0-9]{64})\.(png|jpg|gif|webp)$/
+
+/** Detect supported images from magic bytes; request MIME and filenames are not trusted. */
+export function detectImage(bytes: Uint8Array): ImageKind | undefined {
+  if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47
+    && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) {
+    return { extension: 'png', mime: 'image/png' }
+  }
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return { extension: 'jpg', mime: 'image/jpeg' }
+  }
+  if (bytes.length >= 6) {
+    const head = Buffer.from(bytes.subarray(0, 6)).toString('ascii')
+    if (head === 'GIF87a' || head === 'GIF89a') return { extension: 'gif', mime: 'image/gif' }
+  }
+  if (bytes.length >= 12 && Buffer.from(bytes.subarray(0, 4)).toString('ascii') === 'RIFF'
+    && Buffer.from(bytes.subarray(8, 12)).toString('ascii') === 'WEBP') {
+    return { extension: 'webp', mime: 'image/webp' }
+  }
+  return undefined
+}
+
+/** Files live outside the ledger so state/SSE/tool payloads only carry short Markdown URLs. */
+export class AssetStore {
+  private queue: Promise<unknown> = Promise.resolve()
+  private root: string
+
+  constructor(root: string, private readonly now: () => number = () => Date.now(), private readonly storageQueue?: StorageQueue) { this.root = root }
+
+  /** Current absolute attachment-directory path. */
+  location(): string { return this.root }
+
+  /** Switch reads and future writes after the coordinator copied the directory. */
+  setLocation(root: string): void { this.root = root }
+
+  async put(bytes: Uint8Array, declaredMime?: string): Promise<StoredAsset> {
+    const run = () => this.putSerial(bytes, declaredMime)
+    if (this.storageQueue !== undefined) return this.storageQueue.run(run)
+    return (this.queue = this.queue.then(run, run)) as Promise<StoredAsset>
+  }
+
+  private async putSerial(bytes: Uint8Array, declaredMime?: string): Promise<StoredAsset> {
+    if (bytes.length === 0 || bytes.length > MAX_ASSET_BYTES) {
+      throw new Error(`image must be 1..${MAX_ASSET_BYTES} bytes`)
+    }
+    const kind = detectImage(bytes)
+    if (kind === undefined) throw new Error('unsupported image; use PNG, JPEG, GIF, or WebP')
+    if (declaredMime !== undefined && declaredMime.toLowerCase() !== kind.mime) {
+      throw new Error(`image content does not match ${declaredMime}`)
+    }
+    const id = createHash('sha256').update(bytes).digest('hex')
+    const name = `${id}.${kind.extension}`
+    await mkdir(this.root, { recursive: true })
+    try {
+      const current = await stat(join(this.root, name))
+      if (current.isFile()) return { id, name, size: current.size, url: `/dsh-taskboard/assets/${name}`, ...kind }
+    } catch { /* new content */ }
+
+    let total = 0
+    for (const entry of await readdir(this.root, { withFileTypes: true })) {
+      if (!entry.isFile() || !ASSET_NAME_RE.test(entry.name)) continue
+      try { total += (await stat(join(this.root, entry.name))).size } catch { /* concurrent cleanup */ }
+    }
+    if (total + bytes.length > MAX_ASSET_STORE_BYTES) throw new Error('image store quota exceeded')
+    try {
+      await writeFile(join(this.root, name), bytes, { flag: 'wx' })
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    }
+    return { id, name, size: bytes.length, url: `/dsh-taskboard/assets/${name}`, ...kind }
+  }
+
+  async read(name: string): Promise<{ bytes: Buffer; mime: ImageKind['mime'] } | undefined> {
+    const run = async (): Promise<{ bytes: Buffer; mime: ImageKind['mime'] } | undefined> => {
+    const match = ASSET_NAME_RE.exec(name)
+    if (match === null) return undefined
+    const mime = match[2] === 'png' ? 'image/png'
+      : match[2] === 'jpg' ? 'image/jpeg'
+        : match[2] === 'gif' ? 'image/gif' : 'image/webp'
+    try {
+      return { bytes: await readFile(join(this.root, name)), mime }
+    } catch { return undefined }
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
+  }
+
+  /** Remove abandoned draft uploads after a grace period; referenced files always survive. */
+  async cleanup(referencedContent: string): Promise<number> {
+    const run = async (): Promise<number> => {
+    let entries
+    try { entries = await readdir(this.root, { withFileTypes: true }) } catch { return 0 }
+    let removed = 0
+    for (const entry of entries) {
+      if (!entry.isFile() || !ASSET_NAME_RE.test(entry.name) || referencedContent.includes(entry.name)) continue
+      const path = join(this.root, entry.name)
+      try {
+        const info = await stat(path)
+        if (this.now() - info.mtimeMs < ORPHAN_GRACE_MS) continue
+        await rm(path, { force: true })
+        removed += 1
+      } catch { /* best effort */ }
+    }
+    return removed
+    }
+    return this.storageQueue === undefined ? run() : this.storageQueue.run(run)
+  }
+}

package/src/host/routes.ts

@@ -49,6 +49,8 @@ import { createRepoScanner, type RepoScanner } from './repos.ts'
 import { activeHostLocale } from './locale.ts'
 import type { CatalogModelItem, CatalogPresetItem, MergeRepoResult, TaskTemplate } from '../shared/api.ts'
 import type { TemplateStore } from './templates.ts'
+import { MAX_ASSET_BYTES, type AssetStore } from './assets.ts'
+import type { StorageCoordinator } from './storage.ts'
 import { ROUTE_PREFIX, SSE_PATH, type ApiFail, type ApiResult } from '../shared/api.ts'
 import type { TaskStore } from './store.ts'
 import { ERR, ToolError } from './tools.ts'
@@ -64,6 +66,7 @@ const MAX_BODY_BYTES = 5 * 1024 * 1024
 const TASK_DIFF_RE = new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/diff$`)
 const TASK_RE = new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)$`)
 const TASK_ACTION_RE = new RegExp(`^${ROUTE_PREFIX}/tasks/([^/]+)/([\\w-]+)$`)
+const ASSET_RE = new RegExp(`^${ROUTE_PREFIX}/assets/([a-f0-9]{64}\\.(?:png|jpg|gif|webp))$`)
 
 /** How long a workspace git-detection result stays cached (fail-soft). */
 const GIT_DETECT_TTL_MS = 60_000
@@ -91,6 +94,12 @@ export interface TaskboardRoutesOptions {
   scanner?: RepoScanner
   /** Task-template store (0.4.0); absent → 501 on template actions. */
   templates?: TemplateStore
+  /** Durable image attachment store (0.7.0); absent → attachment routes unavailable. */
+  assets?: AssetStore
+  /** Configurable data-directory coordinator (0.7.0). */
+  storage?: StorageCoordinator
+  /** Initial storage/ledger readiness barrier. */
+  ready?: () => Promise<void>
   /** Prompt completions face (0.5.5; dynamically discovers skills & commands). */
   promptCompletions?: () => Promise<{
     skills?: Array<{ name: string; description?: string }>
@@ -192,6 +201,19 @@ async function readBody(req: IncomingMessage): Promise<Record<string, unknown> |
   }
 }
 
+/** Read one bounded binary upload without ever buffering beyond the file cap. */
+async function readBytes(req: IncomingMessage, limit: number): Promise<Buffer> {
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of req) {
+    const bytes = chunk as Buffer
+    total += bytes.length
+    if (total > limit) throw new Error('body too large')
+    chunks.push(bytes)
+  }
+  return Buffer.concat(chunks)
+}
+
 /** String field accessor (null when absent/not a string). */
 function str(body: Record<string, unknown>, key: string): string | null {
   const v = body[key]
@@ -378,6 +400,25 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
 
       // ---------------------------------------------------------------- GET
       if (req.method === 'GET') {
+        if (pathname === `${ROUTE_PREFIX}/storage`) {
+          if (options.storage === undefined) { res.writeHead(501); res.end(); return }
+          json(res, { ok: true, value: await options.storage.status() })
+          return
+        }
+        await options.ready?.()
+        const assetMatch = pathname.match(ASSET_RE)
+        if (assetMatch !== null) {
+          const asset = await options.assets?.read(assetMatch[1]!)
+          if (asset === undefined) { res.writeHead(404); res.end(); return }
+          res.writeHead(200, {
+            'content-type': asset.mime,
+            'content-length': asset.bytes.length,
+            'cache-control': 'public, max-age=31536000, immutable',
+            'x-content-type-options': 'nosniff',
+          })
+          res.end(asset.bytes)
+          return
+        }
         if (pathname === `${ROUTE_PREFIX}/state`) {
           await store.load()
           json(res, { ok: true, value: { ...store.snapshot(), capabilities: { archiveSessions: typeof workspaces.archiveSession === 'function' } } })
@@ -527,6 +568,34 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         res.end()
         return
       }
+      // Content-addressed image upload. The custom header makes this a
+      // non-simple cross-origin request, preserving the JSON routes' CSRF fence.
+      if (pathname === `${ROUTE_PREFIX}/assets`) {
+        await options.ready?.()
+        if (options.assets === undefined) {
+          const f = fail('invalid_input', 'image attachments unavailable')
+          json(res, f.res, 501)
+          return
+        }
+        if (req.headers['x-dsh-taskboard-upload'] !== '1') {
+          const f = fail('forbidden', 'missing upload header')
+          json(res, f.res, 403)
+          return
+        }
+        const declaredMime = String(req.headers['content-type'] ?? '').split(';', 1)[0]!.trim().toLowerCase()
+        try {
+          const bytes = await readBytes(req, MAX_ASSET_BYTES)
+          await options.assets.cleanup(JSON.stringify(store.snapshot()))
+          const asset = await options.assets.put(bytes, declaredMime)
+          json(res, { ok: true, value: asset }, 201)
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error)
+          const status = message.includes('1..') ? 413 : message.includes('quota') ? 507 : 400
+          const f = fail('invalid_input', message)
+          json(res, f.res, status)
+        }
+        return
+      }
       // CSRF fence: cross-site simple requests cannot set application/json.
       const contentType = req.headers['content-type'] ?? ''
       if (!contentType.toLowerCase().startsWith('application/json')) {
@@ -548,6 +617,29 @@ export function registerTaskboardRoutes(ctx: Context, options: TaskboardRoutesOp
         return
       }
 
+      // Storage location is bootstrap metadata outside the ledger. Keep it on
+      // separate routes so JSON imports and whole-ledger replacement cannot
+      // redirect host filesystem writes.
+      if (pathname === `${ROUTE_PREFIX}/storage/check` || pathname === `${ROUTE_PREFIX}/storage/migrate`) {
+        if (options.storage === undefined) {
+          const f = fail('invalid_input', 'storage configuration unavailable')
+          json(res, f.res, 501)
+          return
+        }
+        try {
+          const directory = str(body, 'directory') ?? ''
+          const value = pathname.endsWith('/check')
+            ? await options.storage.check(directory)
+            : await options.storage.migrate(directory)
+          json(res, { ok: true, value })
+        } catch (error) {
+          const f = fail('invalid_input', error instanceof Error ? error.message : String(error))
+          json(res, f.res, f.status)
+        }
+        return
+      }
+      await options.ready?.()
+
       // ------------------------------------------------- POST /tasks (create)
       if (pathname === `${ROUTE_PREFIX}/tasks`) {
         try {

package/src/host/storage-queue.ts

@@ -0,0 +1,10 @@
+/** One process-wide serial queue shared by all taskboard persistence. */
+export class StorageQueue {
+  private tail: Promise<unknown> = Promise.resolve()
+
+  run<T>(operation: () => Promise<T>): Promise<T> {
+    const result = this.tail.then(operation, operation)
+    this.tail = result.then(() => undefined, () => undefined)
+    return result
+  }
+}