dsh-taskboard 0.6.7 → 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

@@ -11,6 +11,7 @@
 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.
@@ -32,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> {
@@ -59,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')
@@ -71,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)
   }
 
   /**
@@ -85,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()
@@ -102,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)
@@ -113,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

@@ -138,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',
@@ -194,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,
@@ -288,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
         }
       }

package/src/index.ts

@@ -1,7 +1,7 @@
 /**
  * Host loader entry for dsh-taskboard.
  *
- * Wiring: the ledger store (one JSON file under the DSH home), the ten
+ * Wiring: the configurable local data stores, the ten
  * `taskboard_*` agent tools, the agent workflow-protocol system-prompt
  * section, the /taskboard JSON+SSE routes (when a webServer is served),
  * the host execution service (fresh in-project sessions, pinned models), and
@@ -29,14 +29,19 @@ import { dshHomePath } from './host/sdk.ts'
 import { TaskStore } from './host/store.ts'
 import { TemplateStore } from './host/templates.ts'
 import { ExternalSessionSyncService } from './host/session-sync.ts'
-import { registerTaskboardTools, workspaceFace } from './host/tools.ts'
+import { ERR, ToolError, registerTaskboardTools, workspaceFace, type WorkspaceFace } from './host/tools.ts'
+import { AssetStore } from './host/assets.ts'
+import { STORAGE_CONFIG_FILE, StorageCoordinator } from './host/storage.ts'
 
-/** Ledger file name under the DSH home. */
+/** Ledger file name under the active taskboard data directory. */
 export const LEDGER_FILE = 'dsh-taskboard.json'
 
-/** Task-template side file name under the DSH home (0.4.0). */
+/** Task-template side file name under the active data directory. */
 export const TEMPLATES_FILE = 'dsh-taskboard-templates.json'
 
+/** Content-addressed image attachment directory under the active data directory. */
+export const ASSETS_DIR = 'dsh-taskboard-assets'
+
 /** Cordis plugin name. */
 export const name = 'dsh-taskboard'
 
@@ -48,14 +53,24 @@ export const inject = ['tools', 'systemPrompt']
  * @param ctx - the plugin context (tools + systemPrompt injected).
  */
 export function apply(ctx: Context): void {
-  const store = new TaskStore({ file: dshHomePath(LEDGER_FILE) })
-  const templates = new TemplateStore(dshHomePath(TEMPLATES_FILE))
+  const storage = new StorageCoordinator({
+    defaultDirectory: dshHomePath(),
+    configFile: dshHomePath(STORAGE_CONFIG_FILE),
+    ledgerName: LEDGER_FILE,
+    templatesName: TEMPLATES_FILE,
+    assetsName: ASSETS_DIR,
+  })
+  const store = new TaskStore({ file: storage.ledgerPath(), queue: storage.queue })
+  const templates = new TemplateStore(storage.templatesPath(), storage.queue)
+  const assets = new AssetStore(storage.assetsPath(), () => Date.now(), storage.queue)
+  storage.attach({ ledger: store, templates, assets })
   // Eager first load: the tools and most routes read snapshot()/get() without
   // triggering the lazy load, so a fresh boot used to serve an EMPTY board to
   // taskboard_list/get until the scheduler catchup tick or the first
   // GET /state happened to load the file (review P0). load() never throws —
   // a corrupt ledger is quarantined instead.
-  void store.load()
+  const storeReady = storage.ready().then(() => store.load())
+  void storeReady.then(() => assets.cleanup(JSON.stringify(store.snapshot())))
   const now = () => Date.now()
   // Global execution concurrency cap (DSH_TASKBOARD_MAX_CONCURRENT overrides).
   const maxConcurrent = Math.max(1, Number.parseInt(process.env.DSH_TASKBOARD_MAX_CONCURRENT ?? '', 10) || DEFAULT_MAX_CONCURRENT)
@@ -68,29 +83,60 @@ export function apply(ctx: Context): void {
   })
   ctx.effect(() => disposeSection, 'dsh-taskboard: protocol section')
 
-  // Tools, routes, execution, and the scheduler all come up with the
-  // workspace registry (claim boundary + project execution need it).
-  ctx.inject(['workspaceRegistry'], (wsCtx: Context) => {
-    const disposers: Array<() => void> = []
-
-    // Registered model provider routes (from the host llm runtime), read
-    // lazily at call time so late availability still applies; undefined when
-    // the runtime is absent → only structural model validation runs.
-    const modelProviders = (): string[] | undefined => {
-      try {
-        const llm = wsCtx.get('llm') as { listProviders?: () => Array<{ id: string }> } | undefined
-        return llm === undefined || typeof llm.listProviders !== 'function'
-          ? undefined
-          : llm.listProviders().map(p => p.id)
-      } catch { return undefined }
+  // Register the complete tool schema in the same synchronous mount as the
+  // protocol. Keeping schemas stable from the first request preserves the
+  // provider's prefix cache; calls use the live workspace service below.
+  let activeWorkspaces: WorkspaceFace | undefined
+  let activeWorkspaceContext: Context | undefined
+  const requireWorkspaces = (): WorkspaceFace => {
+    if (activeWorkspaces === undefined) {
+      throw new ToolError(ERR.notReady, 'workspace service is not ready; retry after host startup completes')
     }
+    return activeWorkspaces
+  }
+  const workspaces: WorkspaceFace = {
+    resolveByPath: path => requireWorkspaces().resolveByPath(path),
+    get: id => requireWorkspaces().get(id),
+    list: () => requireWorkspaces().list(),
+  }
+  // Preserve the optional archive capability without replacing the stable
+  // facade captured by the tool definitions.
+  Object.defineProperty(workspaces, 'archiveSession', {
+    enumerable: true,
+    get: () => activeWorkspaces?.archiveSession === undefined
+      ? undefined
+      : (sessionId: string) => requireWorkspaces().archiveSession!(sessionId),
+  })
+  const modelProviders = (): string[] | undefined => {
+    try {
+      const llm = activeWorkspaceContext?.get('llm') as { listProviders?: () => Array<{ id: string }> } | undefined
+      return llm === undefined || typeof llm.listProviders !== 'function'
+        ? undefined
+        : llm.listProviders().map(p => p.id)
+    } catch { return undefined }
+  }
+  const disposeTools = registerTaskboardTools(ctx, {
+    store,
+    workspaces,
+    now,
+    modelProviders,
+    ready: async () => {
+      if (activeWorkspaces === undefined) {
+        throw new ToolError(ERR.notReady, 'workspace service is not ready; retry after host startup completes')
+      }
+      await storeReady
+    },
+  })
+  ctx.effect(() => () => {
+    for (const dispose of disposeTools.splice(0)) dispose()
+  }, 'dsh-taskboard: tools')
 
-    disposers.push(...registerTaskboardTools(wsCtx, {
-      store,
-      workspaces: workspaceFace(wsCtx.workspaceRegistry),
-      now,
-      modelProviders,
-    }))
+  // Runtime services come and go with the workspace registry. Tool schemas
+  // remain mounted and resolve this current service only when called.
+  ctx.inject(['workspaceRegistry'], (wsCtx: Context) => {
+    const workspaceDisposers: Array<() => void> = []
+    activeWorkspaces = workspaceFace(wsCtx.workspaceRegistry)
+    activeWorkspaceContext = wsCtx
 
     // Settlement listener over the session event bus.
     const events: EventsFace = {
@@ -122,7 +168,7 @@ export function apply(ctx: Context): void {
       },
       now,
     })
-    disposers.push(() => sessionSync.dispose())
+    workspaceDisposers.push(() => sessionSync.dispose())
 
     // The narrow git face shared by execution (worktree isolation) and the
     // routes (merge / remove / workspace detection), plus the shared
@@ -131,6 +177,7 @@ export function apply(ctx: Context): void {
     const scanner = createRepoScanner()
 
     wsCtx.inject(['agents'], (agentCtx: Context) => {
+      const agentDisposers: Array<() => void> = []
       agentSessions = agentCtx.get('sessions') as { get?: (id: string) => unknown; list?: () => unknown[] } | undefined
       const execution = new ExecutionService({
         store,
@@ -207,6 +254,9 @@ export function apply(ctx: Context): void {
           git,
           scanner,
           templates,
+          assets,
+          storage,
+          ready: async () => { await storeReady },
           promptCompletions: async () => {
             try {
               const skillsService = agentCtx.get('skills') as { list?(options?: unknown): Promise<Array<{ name: string; description?: string }>> } | undefined
@@ -307,19 +357,24 @@ export function apply(ctx: Context): void {
       // browser open. Shares the execution concurrency cap.
       const scheduler = new SchedulerService({ store, execution, now, maxConcurrent })
       scheduler.start()
-      disposers.push(() => scheduler.dispose())
+      agentDisposers.push(() => scheduler.dispose())
       // Detach the settlement listener with the plugin — a hot reload must
       // not leave stale services reacting to turn/end errors (review P1).
-      disposers.push(() => execution.dispose())
+      agentDisposers.push(() => execution.dispose())
 
       return () => {
         disposeRoutes?.()
-        for (const dispose of disposers.splice(0)) dispose()
+        agentSessions = undefined
+        for (const dispose of agentDisposers.splice(0)) dispose()
       }
     })
 
     return () => {
-      for (const dispose of disposers.splice(0)) dispose()
+      if (activeWorkspaceContext === wsCtx) {
+        activeWorkspaceContext = undefined
+        activeWorkspaces = undefined
+      }
+      for (const dispose of workspaceDisposers.splice(0)) dispose()
     }
   })
 }