@mengruo/dsh-vision-toolkit 0.1.3 → 0.1.5

package/src/object-storage.ts

@@ -0,0 +1,174 @@
+/**
+ * Minimal S3-compatible object storage bridge used by the URL image-transfer
+ * path. It uploads one image, resolves a model-reachable URL (a configured
+ * public base URL or a temporary presigned URL), and deletes the object after
+ * the vision operation settles. It also provides the Settings "test storage"
+ * probe (upload → head → delete).
+ * @module dsh-vision-toolkit/object-storage
+ */
+
+import { createHash, randomUUID } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import { basename } from 'node:path'
+import {
+  DeleteObjectCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  type S3ClientConfig,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { VisionToolkitError } from './errors.ts'
+
+/** Fully resolved object-storage connection settings (secrets already filled). */
+export interface ObjectStorageSettings {
+  endpoint: string
+  bucket: string
+  accessKeyId: string
+  secretAccessKey: string
+  publicBase?: string
+}
+
+/** Whether the required connection fields are present enough to attempt a request. */
+export function isObjectStorageConfigured(settings: ObjectStorageSettings): boolean {
+  return settings.endpoint.length > 0
+    && settings.bucket.length > 0
+    && settings.accessKeyId.length > 0
+    && settings.secretAccessKey.length > 0
+}
+
+/** Stable object-key prefix so every upload lives under one deletable namespace. */
+const OBJECT_KEY_PREFIX = 'dsh-vision-toolkit'
+
+function encodeKey(key: string): string {
+  return key.split('/').map(encodeURIComponent).join('/')
+}
+
+function clientFor(settings: ObjectStorageSettings): S3Client {
+  const config: S3ClientConfig = {
+    region: 'auto',
+    forcePathStyle: true,
+    credentials: {
+      accessKeyId: settings.accessKeyId,
+      secretAccessKey: settings.secretAccessKey,
+    },
+  }
+  if (settings.endpoint.length > 0) config.endpoint = settings.endpoint
+  return new S3Client(config)
+}
+
+function publicError(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}
+
+/**
+ * One upload's worth of bookkeeping: the object key and the URL handed to the
+ * model. The key is returned to the runtime so it can delete the object after
+ * the operation settles.
+ */
+export interface UploadedObject {
+  key: string
+  url: string
+}
+
+/** A small S3-compatible object store bound to one bucket and credential. */
+export class ObjectStorageClient {
+  private client?: S3Client
+
+  constructor(private readonly settings: ObjectStorageSettings) {}
+
+  private requireClient(): S3Client {
+    if (this.client === undefined) this.client = clientFor(this.settings)
+    return this.client
+  }
+
+  /** Upload one local image file and resolve its model-reachable URL. */
+  async uploadImage(localPath: string, contentType: string): Promise<UploadedObject> {
+    const body = await readFile(localPath)
+    const digest = createHash('sha256').update(body).digest('hex').slice(0, 12)
+    const name = basename(localPath).replace(/[^A-Za-z0-9._-]/g, '_')
+    const key = `${OBJECT_KEY_PREFIX}/${randomUUID()}-${digest}-${name}`
+    try {
+      await this.requireClient().send(new PutObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+        Body: body,
+        ContentType: contentType,
+      }))
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage upload failed: ${publicError(error)}`, { cause: error })
+    }
+    return { key, url: await this.urlFor(key) }
+  }
+
+  /** Resolve the model-reachable URL: public base URL when set, else presigned. */
+  async urlFor(key: string): Promise<string> {
+    if (this.settings.publicBase !== undefined && this.settings.publicBase.length > 0) {
+      return `${this.settings.publicBase}/${encodeKey(key)}`
+    }
+    try {
+      return await getSignedUrl(
+        this.requireClient(),
+        new GetObjectCommand({ Bucket: this.settings.bucket, Key: key }),
+        { expiresIn: 3600 },
+      )
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage presign failed: ${publicError(error)}`, { cause: error })
+    }
+  }
+
+  /** Delete one uploaded object; failures are logged, never fatal to the call. */
+  async deleteObject(key: string): Promise<void> {
+    try {
+      await this.requireClient().send(new DeleteObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+      }))
+    } catch {
+      // Best-effort cleanup: a failed delete must not mask the vision result.
+    }
+  }
+
+  /** Settings "test storage" probe: upload a tiny object, head it, then delete it. */
+  async test(): Promise<{ detail: string }> {
+    if (!isObjectStorageConfigured(this.settings)) {
+      throw new VisionToolkitError('config', 'object storage is not fully configured (endpoint, bucket, access key id, and secret access key are required)')
+    }
+    const key = `${OBJECT_KEY_PREFIX}/.connection-test-${randomUUID()}`
+    const marker = `dsh-vision-toolkit object storage test ${Date.now()}`
+    try {
+      await this.requireClient().send(new PutObjectCommand({
+        Bucket: this.settings.bucket,
+        Key: key,
+        Body: marker,
+        ContentType: 'text/plain',
+      }))
+      await this.requireClient().send(new HeadObjectCommand({ Bucket: this.settings.bucket, Key: key }))
+      await this.requireClient().send(new DeleteObjectCommand({ Bucket: this.settings.bucket, Key: key }))
+    } catch (error) {
+      throw new VisionToolkitError('service', `object storage test failed: ${publicError(error)}`, { cause: error })
+    }
+    const urlMode = this.settings.publicBase !== undefined && this.settings.publicBase.length > 0
+      ? `public base ${this.settings.publicBase}`
+      : 'presigned URL'
+    return { detail: `bucket ${this.settings.bucket} reachable; model URLs will use ${urlMode}` }
+  }
+}
+
+/**
+ * Split a credential value of the form `accessKeyId:secretAccessKey` into its
+ * two parts. The access key id never contains a colon, so splitting on the
+ * first colon is safe.
+ */
+export function splitObjectStorageCredential(value: string): { accessKeyId: string; secretAccessKey: string } {
+  const index = value.indexOf(':')
+  if (index <= 0) {
+    throw new VisionToolkitError('config', 'object storage credential must be "accessKeyId:secretAccessKey"')
+  }
+  return {
+    accessKeyId: value.slice(0, index),
+    secretAccessKey: value.slice(index + 1),
+  }
+}

package/src/paste-images.ts

@@ -1,11 +1,13 @@
-/** Workspace-local storage for images pasted into the DSH Web composer. */
+/** Plugin-managed storage for images pasted into the DSH Web composer. */
 
 import { createHash, randomUUID } from 'node:crypto'
-import { lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises'
+import { constants as fsConstants } from 'node:fs'
+import { copyFile, lstat, mkdir, open, realpath, rename, rm } from 'node:fs/promises'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from '@deepseek-ai/dsh-session'
+import { resolveWorkspaceStorage } from './paths.ts'
 import { sameOriginPost } from './web-request.ts'
 
 /** Exact route used by the browser paste integration. */
@@ -51,6 +53,7 @@ export interface PasteVerdict {
 }
 
 const MAX_NAME_BYTES = 180
+const MAX_STORAGE_GENERATION_RETRIES = 4
 
 /**
  * Hard per-image upload ceiling for pastes. Files between the configured
@@ -151,7 +154,7 @@ export function safePastedImageName(raw: string, mediaType: string): string {
 export function ensurePathInside(root: string, target: string): void {
   const rel = relative(root, target)
   if (rel !== '' && (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))) {
-    throw new Error(`resolved pasted-image path escapes its workspace root: ${target}`)
+    throw new Error(`resolved pasted-image path escapes its managed root: ${target}`)
   }
 }
 
@@ -168,7 +171,7 @@ async function ensureManagedDirectory(workspace: string, path: string): Promise<
   }
   const entry = await lstat(path)
   if (entry.isSymbolicLink()) {
-    throw new Error(`resolved pasted-image path escapes its workspace root: symbolic link ${path}`)
+    throw new Error(`resolved pasted-image path escapes its managed root: symbolic link ${path}`)
   }
   if (!entry.isDirectory()) throw new Error(`pasted-image path is not a directory: ${path}`)
   const canonical = await realpath(path)
@@ -178,29 +181,33 @@ async function ensureManagedDirectory(workspace: string, path: string): Promise<
 
 /**
  * Resolve the managed per-session image directory used by both browser pastes
- * and native attachment bridging. Keeping both flows under the same workspace
- * root makes the resulting absolute path valid for the model's visual tools.
+ * and native attachment bridging. A configured shared storage root receives a
+ * stable workspace-specific child, keeping projects isolated without writing
+ * plugin files into the project directory.
  */
-export async function sessionPasteRoot(ctx: Context, sessionId: string): Promise<PasteRoot> {
+export async function sessionPasteRoot(
+  ctx: Context,
+  sessionId: string,
+  storageDir?: string,
+): Promise<PasteRoot> {
   const session = ctx.sessions.get(sessionId as never)
   if (session === undefined) throw new Error(`live Session not found: ${sessionId}`)
   const cwd = session.header.cwd
   if (cwd === undefined || !isAbsolute(cwd)) throw new Error(`Session has no absolute workspace: ${sessionId}`)
 
-  const visibleWorkspace = resolve(cwd)
-  const workspace = await realpath(visibleWorkspace)
-  const pluginRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
-  await ensureManagedDirectory(workspace, pluginRoot)
+  const storage = await resolveWorkspaceStorage(resolve(cwd), storageDir)
+  const pluginRoot = storage.root
   const temporaryRoot = join(pluginRoot, 'tmp')
-  await ensureManagedDirectory(workspace, temporaryRoot)
+  await ensureManagedDirectory(pluginRoot, temporaryRoot)
   const requestedRoot = join(temporaryRoot, 'pasted-images')
-  const root = await ensureManagedDirectory(workspace, requestedRoot)
+  const root = await ensureManagedDirectory(temporaryRoot, requestedRoot)
+  const visibleRoot = join(storage.visibleRoot, 'tmp', 'pasted-images')
 
   const sessionKey = createHash('sha256').update(sessionId).digest('hex').slice(0, 20)
   const requestedSessionRoot = join(requestedRoot, sessionKey)
   const sessionRoot = await ensureManagedDirectory(root, requestedSessionRoot)
   ensurePathInside(root, sessionRoot)
-  return { writeRoot: sessionRoot, visibleRoot: requestedSessionRoot }
+  return { writeRoot: sessionRoot, visibleRoot: join(visibleRoot, sessionKey) }
 }
 
 async function writeImage(
@@ -240,9 +247,38 @@ async function writeImage(
   }
 }
 
+async function copyImage(
+  source: string,
+  directory: string,
+  filename: string,
+): Promise<string> {
+  const id = randomUUID()
+  const finalPath = join(directory, `${id}-${filename}`)
+  const stagingPath = join(directory, `.${id}.partial`)
+  ensurePathInside(directory, finalPath)
+  ensurePathInside(directory, stagingPath)
+  try {
+    await copyFile(source, stagingPath, fsConstants.COPYFILE_EXCL)
+    await rename(stagingPath, finalPath)
+    return finalPath
+  } catch (error) {
+    await rm(stagingPath, { force: true }).catch(() => {})
+    throw error
+  }
+}
+
+export interface PasteStorageGeneration {
+  generation: number
+  storageDir?: string
+}
+
+class PasteStorageChangedError extends Error {}
+
 /** Runtime limit face kept separate for focused backend tests. */
 export interface PasteImageRuntime {
   maxUploadBytes(): number
+  storageDirectory?(): string | undefined
+  storageGeneration?(): PasteStorageGeneration
 }
 
 /** Same-origin, live-Session-bound image upload endpoint. */
@@ -252,6 +288,16 @@ export class PastedImageBackend {
     private readonly runtime: PasteImageRuntime,
   ) {}
 
+  private storageGeneration(): PasteStorageGeneration {
+    const current = this.runtime.storageGeneration?.()
+    if (current !== undefined) return current
+    const storageDir = this.runtime.storageDirectory?.()
+    return {
+      generation: 0,
+      ...(storageDir === undefined ? {} : { storageDir }),
+    }
+  }
+
   async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
     if (req.method !== 'POST') {
       res.setHeader('Allow', 'POST')
@@ -263,6 +309,7 @@ export class PastedImageBackend {
       return
     }
 
+    let managedPath: string | undefined
     try {
       const url = new URL(req.url ?? PASTE_IMAGES_ROUTE, 'http://dsh.internal')
       const sessionId = singleQuery(url, 'sessionId')
@@ -273,12 +320,27 @@ export class PastedImageBackend {
       if (contentLength !== undefined && Number(contentLength) !== size) {
         throw new TypeError('Content-Length does not match the declared size')
       }
-      const directory = await sessionPasteRoot(this.ctx, sessionId)
-      const writtenPath = await writeImage(req, directory.writeRoot, filename, size, this.runtime.maxUploadBytes())
-      const absolutePath = join(directory.visibleRoot, basename(writtenPath))
-      responseJson(res, 201, { ok: true, value: { absolutePath, filename, bytes: size } })
+      let storage = this.storageGeneration()
+      let directory = await sessionPasteRoot(this.ctx, sessionId, storage.storageDir)
+      managedPath = await writeImage(req, directory.writeRoot, filename, size, this.runtime.maxUploadBytes())
+      for (let attempt = 0; attempt < MAX_STORAGE_GENERATION_RETRIES; attempt += 1) {
+        const current = this.storageGeneration()
+        if (current.generation === storage.generation && current.storageDir === storage.storageDir) {
+          const absolutePath = join(directory.visibleRoot, basename(managedPath))
+          responseJson(res, 201, { ok: true, value: { absolutePath, filename, bytes: size } })
+          return
+        }
+        const nextDirectory = await sessionPasteRoot(this.ctx, sessionId, current.storageDir)
+        const migratedPath = await copyImage(managedPath, nextDirectory.writeRoot, filename)
+        await rm(managedPath, { force: true }).catch(() => {})
+        managedPath = migratedPath
+        directory = nextDirectory
+        storage = current
+      }
+      throw new PasteStorageChangedError('Vision Toolkit settings changed repeatedly during image copy; retry the paste')
     } catch (error) {
-      const status = error instanceof RangeError ? 413 : 400
+      if (managedPath !== undefined) await rm(managedPath, { force: true }).catch(() => {})
+      const status = error instanceof PasteStorageChangedError ? 409 : error instanceof RangeError ? 413 : 400
       this.ctx.logger.warn('dsh-vision-toolkit pasted image rejected: %s', message(error))
       requestError(res, status, 'paste-image-rejected', message(error))
     }

package/src/paths.ts

@@ -6,9 +6,10 @@
  * @module dsh-vision-toolkit/paths
  */
 
-import { randomUUID } from 'node:crypto'
-import { cp, link, lstat, mkdir, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
-import { extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
+import { createHash, randomUUID } from 'node:crypto'
+import type { Stats } from 'node:fs'
+import { cp, link, lstat, mkdir, mkdtemp, readdir, realpath, rename, rm, stat } from 'node:fs/promises'
+import { dirname, extname, isAbsolute, join, relative, resolve, sep, win32 } from 'node:path'
 import { homedir, tmpdir } from 'node:os'
 import { VisionToolkitError } from './errors.ts'
 
@@ -23,10 +24,22 @@ export interface PathPolicy {
   tempDir: string
   /** Real allowed roots: workspace, platform temp, and configured directories. */
   allowedDirs: string[]
+  /** Real plugin-managed root containing artifacts and transient files. */
+  storageRoot: string
   /** Real plugin-managed output directory inside the fence. */
   outputDir: string
 }
 
+/** Resolved plugin storage for one workspace. */
+export interface WorkspaceStorage {
+  /** Real workspace root. */
+  workspace: string
+  /** Real plugin-managed root for this workspace. */
+  root: string
+  /** Absolute user-visible spelling of the same managed root. */
+  visibleRoot: string
+}
+
 /** Whether `child` equals or lies under `parent` on the same path root. */
 export function isWithin(parent: string, child: string): boolean {
   const rel = relative(parent, child)
@@ -65,26 +78,231 @@ export function normalizePlatformTempPath(
   return win32.join(tempDirectory, raw.slice('/tmp/'.length))
 }
 
+/** Stable opaque per-user workspace id used below a shared storage root. */
+export function workspaceStorageId(
+  workspace: string,
+  userIdentity: string = typeof process.geteuid === 'function'
+    ? `uid:${process.geteuid()}`
+    : `home:${homedir()}`,
+): string {
+  return createHash('sha256')
+    .update(userIdentity)
+    .update('\0')
+    .update(workspace)
+    .digest('hex')
+    .slice(0, 20)
+}
+
+function currentPosixUid(): number {
+  if (typeof process.geteuid !== 'function') {
+    throw new VisionToolkitError(
+      'path',
+      'configured storage directory is not supported on this platform because ownership and permissions cannot be verified',
+    )
+  }
+  return process.geteuid()
+}
+
+export function assertSecureWorkspaceStorage(info: Stats, requested: string): void {
+  const currentUid = currentPosixUid()
+  if (info.uid !== currentUid || (info.mode & 0o777) !== 0o700) {
+    throw new VisionToolkitError('path', `workspace storage directory must be owned by the current user with mode 0700: ${requested}`)
+  }
+}
+
+/** Resolve a shared base and prove every POSIX ancestor is protected from replacement. */
+export async function assertSecureSharedStorageBase(requested: string): Promise<string> {
+  const currentUid = currentPosixUid()
+  const requestedPath = resolve(requested)
+  const requestedChain: string[] = []
+  let requestedCurrent = requestedPath
+  while (true) {
+    requestedChain.push(requestedCurrent)
+    const parent = dirname(requestedCurrent)
+    if (parent === requestedCurrent) break
+    requestedCurrent = parent
+  }
+  for (const component of requestedChain.reverse()) {
+    const info = await lstat(component)
+    if (info.isSymbolicLink()) {
+      if (info.uid !== 0) {
+        throw new VisionToolkitError('path', `configured storage directory contains an untrusted symbolic link: ${component}`)
+      }
+      continue
+    }
+    if (!info.isDirectory()) {
+      throw new VisionToolkitError('path', `configured storage path component is not a directory: ${component}`)
+    }
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${component}`)
+  }
+  const canonical = await realpath(requestedPath)
+  let current = canonical
+  while (true) {
+    const info = await lstat(current)
+    const writableByOthers = (info.mode & 0o022) !== 0
+    const sticky = (info.mode & 0o1000) !== 0
+    if (
+      info.isSymbolicLink()
+      || !info.isDirectory()
+      || (info.uid !== currentUid && info.uid !== 0)
+      || (writableByOthers && !sticky)
+    ) throw new VisionToolkitError('path', `configured storage directory has an untrusted path component: ${current}`)
+    const parent = dirname(current)
+    if (parent === current) return canonical
+    current = parent
+  }
+}
+
+function requestedSharedStorageBase(storageDirRaw: string): string {
+  currentPosixUid()
+  const configured = normalizePlatformTempPath(expandUserHome(storageDirRaw.trim()))
+  if (!isAbsolute(configured)) {
+    throw new VisionToolkitError('path', `configured storage directory must be an absolute path: ${storageDirRaw}`)
+  }
+  return resolve(configured)
+}
+
+async function ensureSharedStorageBase(storageDirRaw: string): Promise<{ requestedBase: string; base: string }> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  try {
+    await mkdir(requestedBase, { recursive: true, mode: 0o700 })
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not writable: ${requestedBase}`, { cause: error })
+  }
+  try {
+    return { requestedBase, base: await assertSecureSharedStorageBase(requestedBase) }
+  } catch (error) {
+    throw new VisionToolkitError('path', `configured storage directory is not accessible: ${requestedBase}`, { cause: error })
+  }
+}
+
+/** Validate and write-probe a configured shared root before Settings activation. */
+export async function preflightSharedStorageBase(storageDirRaw: string): Promise<string> {
+  const { base } = await ensureSharedStorageBase(storageDirRaw)
+  let probe: string | undefined
+  let failure: unknown
+  try {
+    probe = await mkdtemp(join(base, '.dsh-vision-toolkit-preflight-'))
+    assertSecureWorkspaceStorage(await lstat(probe), probe)
+  } catch (error) {
+    failure = error
+  }
+  if (probe !== undefined) {
+    try {
+      await rm(probe, { recursive: true, force: true })
+    } catch (error) {
+      failure ??= error
+    }
+  }
+  if (failure !== undefined) {
+    throw new VisionToolkitError('path', `configured storage directory failed its write preflight: ${base}`, { cause: failure })
+  }
+  return base
+}
+
+async function managedDirectory(
+  parent: string,
+  requested: string,
+  label: string,
+  secureWorkspaceStorage = false,
+): Promise<string> {
+  try {
+    await mkdir(requested, { mode: 0o700 })
+  } catch (error) {
+    if (!(error instanceof Error && 'code' in error && error.code === 'EEXIST')) {
+      throw new VisionToolkitError('path', `${label} is not writable: ${requested}`, { cause: error })
+    }
+  }
+  let info
+  try {
+    info = await lstat(requested)
+  } catch (error) {
+    throw new VisionToolkitError('path', `${label} is not accessible: ${requested}`, { cause: error })
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `${label} must be a real directory: ${requested}`)
+  }
+  if (secureWorkspaceStorage) assertSecureWorkspaceStorage(info, requested)
+  const canonical = await realpath(requested)
+  if (!isWithin(parent, canonical)) {
+    throw new VisionToolkitError('path', `${label} escaped its configured root: ${requested}`)
+  }
+  return canonical
+}
+
+/**
+ * Resolve the plugin-managed root for one workspace. Blank configuration keeps
+ * the legacy workspace-local `.dsh-vision-toolkit` directory. A configured
+ * shared root receives one stable, automatically generated workspace child.
+ */
+export async function resolveWorkspaceStorage(
+  workspaceRaw: string,
+  storageDirRaw?: string,
+): Promise<WorkspaceStorage> {
+  const expandedWorkspace = expandUserHome(workspaceRaw)
+  const visibleWorkspace = resolve(expandedWorkspace)
+  let workspace: string
+  try {
+    workspace = await realpath(visibleWorkspace)
+  } catch (error) {
+    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
+  }
+
+  if (storageDirRaw === undefined || storageDirRaw.trim().length === 0) {
+    const visibleRoot = join(visibleWorkspace, '.dsh-vision-toolkit')
+    const root = await managedDirectory(workspace, visibleRoot, 'plugin storage directory')
+    return { workspace, root, visibleRoot }
+  }
+
+  const { requestedBase, base } = await ensureSharedStorageBase(storageDirRaw)
+  const id = workspaceStorageId(workspace)
+  const visibleRoot = join(requestedBase, id)
+  const root = await managedDirectory(base, join(base, id), 'workspace storage directory', true)
+  return { workspace, root, visibleRoot }
+}
+
+async function resolveReadableWorkspaceStorageRoot(
+  workspace: string,
+  storageDirRaw: string,
+): Promise<string> {
+  const requestedBase = requestedSharedStorageBase(storageDirRaw)
+  const base = await assertSecureSharedStorageBase(requestedBase)
+  const requestedRoot = join(base, workspaceStorageId(workspace))
+  const info = await lstat(requestedRoot)
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new VisionToolkitError('path', `historical workspace storage must be a real directory: ${requestedRoot}`)
+  }
+  assertSecureWorkspaceStorage(info, requestedRoot)
+  const root = await realpath(requestedRoot)
+  if (!isWithin(base, root)) {
+    throw new VisionToolkitError('path', `historical workspace storage escaped its configured root: ${requestedRoot}`)
+  }
+  return root
+}
+
 /**
- * Build the per-invocation path policy: realpath the workspace, resolve and
- * realpath the platform temp directory and allowed directories, and create
- * the output directory inside the fence.
+ * Build the per-invocation path policy: resolve workspace storage, realpath the
+ * platform temp directory and allowed directories, and create the artifact
+ * directory inside the managed root.
  * @param workspaceRaw - session workspace (or process cwd fallback).
  * @param allowedDirs - configured extra allowed roots.
- * @param outputDirRaw - configured output directory (default `.dsh-vision-toolkit/artifacts`).
+ * @param storageDirRaw - optional shared storage root.
+ * @param readableStorageDirs - previously validated shared roots retained for persisted input paths.
  * @returns the resolved policy.
  */
 export async function createPathPolicy(
   workspaceRaw: string,
   allowedDirs: readonly string[],
-  outputDirRaw?: string,
+  storageDirRaw?: string,
+  readableStorageDirs: readonly string[] = [],
 ): Promise<PathPolicy> {
-  let workspace: string
-  try {
-    workspace = await realpath(expandUserHome(workspaceRaw))
-  } catch (error) {
-    throw new VisionToolkitError('path', `workspace is not accessible: ${workspaceRaw}`, { cause: error })
-  }
+  const storage = await resolveWorkspaceStorage(workspaceRaw, storageDirRaw)
+  const { workspace } = storage
   let tempDir: string
   const tempDirectoryRaw = platformTempDirectory()
   try {
@@ -92,7 +310,16 @@ export async function createPathPolicy(
   } catch (error) {
     throw new VisionToolkitError('path', `platform temporary directory is not accessible: ${tempDirectoryRaw}`, { cause: error })
   }
-  const roots = [workspace, tempDir]
+  const roots = [workspace, tempDir, storage.root]
+  for (const raw of readableStorageDirs) {
+    if (raw === storageDirRaw) continue
+    try {
+      roots.push(await resolveReadableWorkspaceStorageRoot(workspace, raw))
+    } catch {
+      // Historical roots are read-only compatibility fences. Missing or newly
+      // unsafe roots stay unauthorized without breaking the active runtime.
+    }
+  }
   for (const raw of allowedDirs) {
     const candidate = expandUserHome(raw)
     const target = isAbsolute(candidate) ? candidate : resolve(workspace, candidate)
@@ -102,20 +329,14 @@ export async function createPathPolicy(
       throw new VisionToolkitError('path', `allowedDirs entry is not accessible: ${raw}`, { cause: error })
     }
   }
-  const outputRaw = outputDirRaw === undefined || outputDirRaw.trim().length === 0
-    ? join(workspace, '.dsh-vision-toolkit', 'artifacts')
-    : resolve(workspace, expandUserHome(outputDirRaw))
-  if (!roots.some(root => isWithin(root, outputRaw))) {
-    throw new VisionToolkitError('path', 'output directory must stay inside the workspace or an allowedDirs entry')
-  }
-  let outputDir: string
-  try {
-    await mkdir(outputRaw, { recursive: true })
-    outputDir = await realpath(outputRaw)
-  } catch (error) {
-    throw new VisionToolkitError('path', `output directory is not writable: ${outputRaw}`, { cause: error })
+  const outputDir = await managedDirectory(storage.root, join(storage.root, 'artifacts'), 'artifact directory')
+  return {
+    workspace,
+    tempDir,
+    allowedDirs: [...new Set(roots)],
+    storageRoot: storage.root,
+    outputDir,
   }
-  return { workspace, tempDir, allowedDirs: [...new Set(roots)], outputDir }
 }
 
 /**