pinokiod 8.0.39 → 8.0.41

package/test/vault-sweep.test.js

@@ -5,6 +5,8 @@ const os = require('os')
 const path = require('path')
 const crypto = require('crypto')
 const Vault = require('../kernel/vault')
+const Registry = require('../kernel/vault/registry')
+const { walkBatches } = require('../kernel/vault/walker')
 
 const sha256 = (buf) => crypto.createHash('sha256').update(buf).digest('hex')
 
@@ -37,6 +39,77 @@ describe('vault manual scan (phase 3)', () => {
     }
   })
 
+  test('directory traversal yields bounded entry chunks without skipping nested files', async () => {
+    const root = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-walk-'))
+    homes.push(root)
+    const expected = []
+    for (let index = 0; index < 7; index++) {
+      expected.push(await writeFile(path.resolve(root, `dir-${index % 2}`, `file-${index}.bin`), String(index)))
+    }
+    const found = []
+    let dirs = 0
+    for await (const batch of walkBatches(root, { concurrency: 2, entryBatchSize: 2 })) {
+      for (const group of batch) {
+        if (group.entries) assert.ok(group.entries.length <= 2)
+        if (group.firstChunk) dirs += 1
+        found.push(...group.files.map((file) => file.path))
+      }
+    }
+    assert.deepStrictEqual(found.sort(), expected.sort())
+    assert.strictEqual(dirs, 3)
+  })
+
+  test('directory traversal resolves unknown entry types before deciding whether to recurse', async () => {
+    const root = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-walk-unknown-'))
+    homes.push(root)
+    const expected = await writeFile(path.resolve(root, 'nested', 'file.bin'), 'data')
+    const realOpendir = fs.promises.opendir
+    fs.promises.opendir = async (dir, options) => {
+      const handle = await realOpendir(dir, options)
+      if (path.resolve(dir) !== root) return handle
+      return {
+        read: async () => {
+          const entry = await handle.read()
+          if (!entry || entry.name !== 'nested') return entry
+          return {
+            name: entry.name,
+            isDirectory: () => false,
+            isFile: () => false,
+            isSymbolicLink: () => false
+          }
+        },
+        close: () => handle.close()
+      }
+    }
+    const found = []
+    try {
+      for await (const batch of walkBatches(root, { concurrency: 2, entryBatchSize: 2 })) {
+        found.push(...batch.flatMap((group) => group.files.map((file) => file.path)))
+      }
+    } finally {
+      fs.promises.opendir = realOpendir
+    }
+    assert.deepStrictEqual(found, [expected])
+  })
+
+  test('directory traversal follows only an explicitly configured symlink root', async (t) => {
+    const realRoot = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-walk-real-'))
+    const linkRoot = path.resolve(os.tmpdir(), `pinokio-walk-link-${crypto.randomUUID()}`)
+    homes.push(realRoot, linkRoot)
+    await writeFile(path.resolve(realRoot, 'nested', 'file.bin'), 'data')
+    try {
+      await fs.promises.symlink(realRoot, linkRoot, process.platform === 'win32' ? 'junction' : 'dir')
+    } catch (error) {
+      t.skip(`directory links unavailable: ${error.message}`)
+      return
+    }
+    const found = []
+    for await (const batch of walkBatches(linkRoot)) {
+      found.push(...batch.flatMap((group) => group.files.map((file) => file.path)))
+    }
+    assert.deepStrictEqual(found, [path.resolve(linkRoot, 'nested', 'file.bin')])
+  })
+
   test('scan discovers, hashes, adopts — and records folder totals', async () => {
     const { home, vault } = await makeEnv()
     const content = crypto.randomBytes(4096)
@@ -48,10 +121,45 @@ describe('vault manual scan (phase 3)', () => {
     assert.ok(result.bytes_total >= content.length + 4, 'folder total includes small files')
     assert.ok(vault.registry.lastScan && vault.registry.lastScan.bytes_total === result.bytes_total)
     assert.ok(vault.registry.lastScan.duration_ms >= 0, 'scan duration is measured')
+    assert.ok(vault.registry.lastScan.count_duration_ms >= 0, 'count duration is measured')
     assert.ok(vault.registry.lastScan.walk_duration_ms >= 0, 'walk duration is measured')
     assert.ok(vault.registry.lastScan.hash_duration_ms >= 0, 'hash duration is measured')
     assert.strictEqual(vault.registry.lastScan.hash_total, 1, 'hash work has a determinate total after walking')
-    assert.deepStrictEqual(vault.registry.lastScan.source_ids, ['pinokio'], 'scan source set is recorded for later estimates')
+    assert.strictEqual(vault.sweeper.state.total_files, 2, 'scan progress uses an exact pre-count')
+  })
+
+  test('an app-scoped scan walks only that app and preserves unrelated registry state', async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const appAFile = await writeFile(path.resolve(home, 'api', 'appA', 'model.bin'), content)
+    const appBFile = await writeFile(path.resolve(home, 'api', 'appB', 'model.bin'), content)
+    await fs.promises.mkdir(path.resolve(home, 'api', 'emptyApp'))
+    await vault.sweeper.scan()
+    const appA = vault.sources().find((source) => source.kind === 'app' && source.app === 'appA')
+    const emptyApp = vault.sources().find((source) => source.kind === 'app' && source.app === 'emptyApp')
+    assert.ok(appA)
+    assert.strictEqual(vault.registry.scanFor(emptyApp.id).files, 0,
+      'a global scan refreshes the baseline for an empty app')
+    assert.strictEqual(vault.registry.duplicates.has(appBFile), true)
+    const globalScan = JSON.parse(JSON.stringify(vault.registry.lastScan))
+
+    await fs.promises.unlink(appBFile)
+    const result = await vault.sweeper.scan(appA.id)
+
+    assert.strictEqual(result.files, 1)
+    assert.strictEqual(result.bytes_total, content.length)
+    assert.deepStrictEqual(vault.registry.lastScan, globalScan, 'app scan does not replace global totals')
+    assert.strictEqual(vault.registry.duplicates.has(appBFile), true,
+      'scoped verification does not reconcile another app')
+    assert.strictEqual(vault.registry.links.has(appAFile), true)
+    assert.strictEqual(vault.registry.scanFor(appA.id).files, 1)
+    assert.strictEqual(vault.registry.scanFor(appA.id).bytes_total, content.length)
+    await vault.registry.flush()
+    const snapshot = JSON.parse(await fs.promises.readFile(vault.registry.snapshotPath, 'utf8'))
+    assert.strictEqual(snapshot.scans[appA.id].last_complete.bytes_total, content.length)
+    const reloaded = new Registry(vault.root)
+    await reloaded.load()
+    assert.strictEqual(reloaded.scanFor(appA.id).bytes_total, content.length)
   })
 
   test('scans NEVER convert: every byte-identical copy is pending, even in HF caches', async () => {
@@ -71,9 +179,20 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual(events.filter((e) => e.kind === 'convert').length, 0, 'no conversion without a click')
     assert.ok(events.some((e) => e.kind === 'found'))
 
-    const summary = await vault.sweeper.convertPending(undefined)
-    assert.strictEqual(summary.converted, 2)
+    let converted = 0
+    for (const scopeId of new Set([...vault.registry.duplicates.values()].map((entry) => entry.source_id))) {
+      const paths = [...vault.registry.duplicates]
+        .filter(([, entry]) => entry.source_id === scopeId)
+        .map(([filePath]) => filePath)
+      const summary = await vault.perform('deduplicate', { scope_id: scopeId, paths })
+      converted += summary.converted
+    }
+    assert.strictEqual(converted, 2)
     assert.strictEqual((await fs.promises.stat(a)).ino, (await fs.promises.stat(b)).ino)
+
+    await vault.sweeper.scan()
+    assert.strictEqual(vault.registry.lastScan.hashed, 0,
+      'Vault-authored inode and ctime changes refresh the exact scan snapshots')
   })
 
   test('no name heuristics: files inside venv-like folders are found', async () => {
@@ -85,6 +204,26 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual((await fs.promises.stat(inVenv)).nlink, 2, 'adopted despite venv-ish path')
   })
 
+  test('a tracked Hugging Face blob that changes below the threshold is rehashed', async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const hash = sha256(content)
+    const file = await writeFile(
+      path.resolve(home, 'api', 'appA', 'cache', 'models--org--model', 'blobs', hash), content)
+    await vault.sweeper.scan()
+    assert.strictEqual(vault.registry.links.has(file), true)
+
+    await fs.promises.truncate(file, 512)
+    await vault.sweeper.scan()
+
+    const changedHash = sha256(await fs.promises.readFile(file))
+    assert.strictEqual(vault.registry.links.get(file).hash, changedHash)
+    assert.strictEqual(vault.registry.scanIndex.get(file).hash, changedHash)
+    assert.strictEqual(vault.registry.blobs.has(hash), false)
+    assert.strictEqual(vault.registry.blobs.has(changedHash), true)
+    assert.strictEqual((await fs.promises.stat(file)).size, 512)
+  })
+
   test('symlinked dirs and files are skipped; cycles cannot hang the walk', async () => {
     const { home, vault } = await makeEnv()
     const real = await writeFile(path.resolve(home, 'api', 'appA', 'models', 'real.bin'), crypto.randomBytes(4096))
@@ -93,42 +232,71 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual((await fs.promises.stat(real)).nlink, 2)
   })
 
-  test('top-level linked imports are scanned as external sources while nested links stay skipped', async (t) => {
+  test('a file replaced by a symlink during inspection is never followed', async (t) => {
+    const { home, vault } = await makeEnv()
+    const outsideRoot = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-scan-race-outside-'))
+    homes.push(outsideRoot)
+    const outside = await writeFile(path.resolve(outsideRoot, 'outside.bin'), crypto.randomBytes(4096))
+    const outsideHash = sha256(await fs.promises.readFile(outside))
+    const candidate = await writeFile(path.resolve(home, 'api', 'appA', 'candidate.bin'), crypto.randomBytes(4096))
+    const realLstat = fs.promises.lstat
+    let replaced = false
+    fs.promises.lstat = async (target, options) => {
+      if (!replaced && path.resolve(target) === candidate) {
+        replaced = true
+        await fs.promises.unlink(candidate)
+        try {
+          await fs.promises.symlink(outside, candidate, 'file')
+        } catch (error) {
+          if (error.code === 'EPERM' || error.code === 'EACCES') {
+            await fs.promises.copyFile(outside, candidate)
+            t.skip(`file symlinks unavailable: ${error.message}`)
+          } else {
+            throw error
+          }
+        }
+      }
+      return realLstat(target, options)
+    }
+    try {
+      await vault.sweeper.scan()
+    } finally {
+      fs.promises.lstat = realLstat
+    }
+    if (!replaced || !(await realLstat(candidate)).isSymbolicLink()) return
+
+    assert.strictEqual(vault.registry.scanIndex.has(candidate), false)
+    assert.strictEqual(vault.registry.blobs.has(outsideHash), false)
+    assert.strictEqual((await fs.promises.stat(outside)).nlink, 1)
+  })
+
+  test('filesystem links under api are never treated as external scan sources', async (t) => {
     const { home, vault } = await makeEnv()
     const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-'))
-    const nested = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-nested-'))
-    homes.push(external, nested)
+    homes.push(external)
     const content = crypto.randomBytes(4096)
     const local = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
     const imported = await writeFile(path.resolve(external, 'models', 'm.bin'), content)
-    const nestedFile = await writeFile(path.resolve(nested, 'should-not-scan.bin'), crypto.randomBytes(4096))
     try {
       await fs.promises.symlink(external, path.resolve(home, 'api', 'linked-models'), process.platform === 'win32' ? 'junction' : 'dir')
-      await fs.promises.symlink(nested, path.resolve(external, 'nested-link'), process.platform === 'win32' ? 'junction' : 'dir')
     } catch (error) {
       t.skip(`directory links unavailable: ${error.message}`)
       return
     }
 
     await vault.sweeper.scan()
-    const source = vault.sources().find((item) => item.kind === 'external' && item.label === 'linked-models')
     const canonicalImported = path.resolve(await fs.promises.realpath(external), 'models', 'm.bin')
-    const canonicalNestedFile = path.resolve(await fs.promises.realpath(nested), 'should-not-scan.bin')
-    assert.ok(source, 'linked import becomes an external source')
-    assert.strictEqual(source.parent_id, 'external')
-    assert.ok(vault.registry.scanIndex.has(canonicalImported), 'external root was scanned')
-    assert.strictEqual(vault.registry.scanIndex.has(canonicalNestedFile), false, 'nested directory link was not followed')
-    assert.strictEqual(vault.registry.duplicates.get(canonicalImported).source_id, source.id)
+    assert.strictEqual(vault.sources().some((item) => item.kind === 'external'), false)
+    assert.strictEqual(vault.registry.scanIndex.has(canonicalImported), false)
     assert.strictEqual((await fs.promises.stat(local)).nlink, 2)
 
     const status = await vault.status()
-    assert.ok(status.sources.some((item) => item.id === source.id && item.kind === 'external'))
-    assert.strictEqual(status.duplicates.find((item) => item.path === canonicalImported).source_id, source.id)
+    assert.strictEqual(status.sources.some((item) => item.kind === 'external'), false)
     assert.strictEqual(status.last_scan.home_bytes_total, content.length, 'Pinokio metric excludes external files')
-    assert.strictEqual(status.last_scan.source_bytes[source.id], content.length, 'external totals remain attributable')
+    assert.strictEqual(fs.existsSync(imported), true)
   })
 
-  test('adding an external source creates one persistent import without starting a scan', async () => {
+  test('adding an external source persists only its canonical registry path', async () => {
     const { home, vault } = await makeEnv()
     const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-added-external-'))
     homes.push(external)
@@ -140,14 +308,241 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual(added.source.kind, 'external')
     assert.strictEqual(added.source.parent_id, 'external')
     assert.strictEqual(vault.registry.scanIndex.size, 0, 'adding a source never scans it')
-    assert.strictEqual((await fs.promises.lstat(added.source.mount_path)).isSymbolicLink(), true)
+    assert.deepStrictEqual(vault.registry.settings.external_sources, [await fs.promises.realpath(external)])
+    assert.strictEqual(fs.existsSync(path.resolve(home, 'vault', 'sources')), false)
+    assert.deepStrictEqual(await fs.promises.readdir(path.resolve(home, 'api')), [],
+      'adding a source never creates an app alias')
 
     const repeated = await vault.addExternalSource(external)
-    assert.strictEqual(repeated.created, false, 'the same physical folder is not imported twice')
+    assert.strictEqual(repeated.created, false, 'the same physical folder is not registered twice')
     assert.strictEqual(vault.sources().filter((source) => source.kind === 'external').length, 1)
 
+    const reloaded = new Registry(path.resolve(home, 'vault'))
+    await reloaded.load()
+    assert.deepStrictEqual(reloaded.settings.external_sources, [await fs.promises.realpath(external)])
+
+    await vault.sweeper.scan()
+    const canonicalImported = path.resolve(await fs.promises.realpath(imported))
+    assert.ok(vault.registry.scanIndex.has(canonicalImported))
+
+    const removed = await vault.perform('remove_source', { source_id: added.source.id })
+    assert.strictEqual(removed.removed, true)
+    const status = await vault.status()
+    assert.strictEqual(vault.registry.links.has(canonicalImported), false)
+    assert.strictEqual(vault.registry.duplicates.has(canonicalImported), false)
+    assert.strictEqual(vault.registry.scanIndex.has(canonicalImported), false)
+    assert.strictEqual(status.sources.some((source) => source.kind === 'external'), false)
+    assert.strictEqual(status.duplicates.some((item) => item.path === canonicalImported), false)
+    assert.deepStrictEqual(vault.registry.settings.external_sources, [])
+    assert.deepStrictEqual(await fs.promises.readFile(imported), content)
+  })
+
+  test('deleting Vault state resets configured external sources without touching them', async () => {
+    const { home, kernel, vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-reset-'))
+    homes.push(external)
+    const externalFile = await writeFile(path.resolve(external, 'model.bin'), 'external data')
+    await vault.addExternalSource(external)
+    await fs.promises.rm(vault.root, { recursive: true, force: true })
+
+    const fresh = new Vault(kernel)
+    await fresh.init()
+
+    assert.deepStrictEqual(fresh.registry.settings.external_sources, [])
+    assert.strictEqual(fresh.sources().some((source) => source.kind === 'external'), false)
+    assert.strictEqual(await fs.promises.readFile(externalFile, 'utf8'), 'external data')
+  })
+
+  test('external sources cannot overlap', async () => {
+    const { vault } = await makeEnv()
+    const parent = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-parent-'))
+    const child = path.resolve(parent, 'child')
+    homes.push(parent)
+    await fs.promises.mkdir(child, { recursive: true })
+    await vault.addExternalSource(parent)
+    await assert.rejects(vault.addExternalSource(child), /does not contain or overlap/)
+    assert.strictEqual(vault.registry.settings.external_sources.length, 1)
+  })
+
+  test('removing an external source is refused while one of its files is shared', async () => {
+    const { home, vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-shared-'))
+    homes.push(external)
+    const content = crypto.randomBytes(4096)
+    await writeFile(path.resolve(home, 'api', 'appA', 'model.bin'), content)
+    const externalFile = await writeFile(path.resolve(external, 'model.bin'), content)
+    const source = (await vault.addExternalSource(external)).source
+
+    await vault.sweeper.scan()
+    const converted = await vault.deduplicateScope(source.id)
+    assert.strictEqual(converted.converted, 1)
+    assert.strictEqual((await fs.promises.stat(externalFile)).nlink, 3)
+
+    await assert.rejects(
+      vault.removeExternalSource(source.id),
+      /Turn sharing off/
+    )
+    assert.deepStrictEqual(vault.registry.settings.external_sources, [await fs.promises.realpath(external)])
+    assert.strictEqual(fs.existsSync(externalFile), true)
+  })
+
+  test('an unavailable external source must be reconnected before removal', async () => {
+    const { vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-offline-'))
+    const moved = `${external}-moved`
+    homes.push(moved)
+    const source = (await vault.addExternalSource(external)).source
+    await fs.promises.rename(external, moved)
+
+    await assert.rejects(
+      vault.removeExternalSource(source.id),
+      /Reconnect this folder/
+    )
+    assert.deepStrictEqual(vault.registry.settings.external_sources, [source.root])
+  })
+
+  test('an unavailable configured source makes a global scan incomplete without erasing it', async () => {
+    const { vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-scan-offline-'))
+    const moved = `${external}-moved`
+    homes.push(moved)
+    await writeFile(path.resolve(external, 'model.bin'), crypto.randomBytes(4096))
+    const source = (await vault.addExternalSource(external)).source
+    const externalFile = path.resolve(source.root, 'model.bin')
+    await vault.sweeper.scan()
+    const beforeScan = JSON.parse(JSON.stringify(vault.registry.lastScan))
+    assert.strictEqual(vault.registry.links.has(externalFile), true)
+    await fs.promises.rename(external, moved)
+
+    const result = await vault.sweeper.scan()
+
+    assert.strictEqual(result.incomplete, true)
+    assert.deepStrictEqual(vault.registry.lastScan, beforeScan)
+    assert.strictEqual(vault.registry.links.has(externalFile), true)
+    assert.deepStrictEqual(vault.sweeper.state.inaccessible_paths, [source.root])
+  })
+
+  test('a transient source-enumeration error preserves the last complete source map', async () => {
+    const { home, vault } = await makeEnv()
+    await fs.promises.mkdir(path.resolve(home, 'api', 'appA'), { recursive: true })
+    await vault.refreshSources()
+    const before = vault.sources().map((source) => source.id)
+    const apiRoot = path.resolve(home, 'api')
+    const realReaddir = fs.promises.readdir
+    fs.promises.readdir = async (target, options) => {
+      if (path.resolve(target) === apiRoot) {
+        const error = new Error('transient read failure')
+        error.code = 'EIO'
+        throw error
+      }
+      return realReaddir(target, options)
+    }
+    try {
+      await assert.rejects(vault.refreshSources(), (error) => error.code === 'EIO')
+    } finally {
+      fs.promises.readdir = realReaddir
+    }
+
+    assert.deepStrictEqual(vault.sources().map((source) => source.id), before)
+    assert.ok(vault.sources().some((source) => source.kind === 'app' && source.app === 'appA'))
+  })
+
+  test('a transient external-source metadata error fails the scan without publishing an incomplete result', async () => {
+    const { vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-external-metadata-'))
+    homes.push(external)
+    await writeFile(path.resolve(external, 'model.bin'), crypto.randomBytes(4096))
+    await vault.addExternalSource(external)
+    await vault.sweeper.scan()
+    const beforeScan = JSON.parse(JSON.stringify(vault.registry.lastScan))
+    const beforeSources = vault.sources().map((source) => source.id)
+    const canonicalExternal = await fs.promises.realpath(external)
+    const realLstat = fs.promises.lstat
+    let externalStats = 0
+    fs.promises.lstat = async (target, options) => {
+      if (path.resolve(String(target)) === path.resolve(canonicalExternal) && ++externalStats === 1) {
+        const error = new Error('temporary external metadata failure')
+        error.code = 'EIO'
+        throw error
+      }
+      return realLstat(target, options)
+    }
+    try {
+      await assert.rejects(vault.sweeper.scan(), (error) => error && error.code === 'EIO')
+    } finally {
+      fs.promises.lstat = realLstat
+    }
+
+    assert.deepStrictEqual(vault.registry.lastScan, beforeScan)
+    assert.deepStrictEqual(vault.sources().map((source) => source.id), beforeSources)
+    assert.strictEqual(vault.sweeper.state.phase, 'failed')
+  })
+
+  test('an access-denied subtree is skipped without erasing its records or exact scan totals', async () => {
+    const { home, vault } = await makeEnv()
+    const deniedDir = path.resolve(home, 'api', 'appA', 'private')
+    const deniedFile = await writeFile(path.resolve(deniedDir, 'model.bin'), crypto.randomBytes(4096))
     await vault.sweeper.scan()
-    assert.ok(vault.registry.scanIndex.has(path.resolve(await fs.promises.realpath(imported))))
+    const beforeScan = JSON.parse(JSON.stringify(vault.registry.lastScan))
+    assert.strictEqual(vault.registry.links.has(deniedFile), true)
+
+    const accessibleFile = await writeFile(
+      path.resolve(home, 'api', 'appB', 'model.bin'),
+      crypto.randomBytes(4096)
+    )
+    const realLstat = fs.promises.lstat
+    fs.promises.lstat = async (target, options) => {
+      if (path.resolve(String(target)) === deniedDir) {
+        const error = new Error('permission denied')
+        error.code = 'EACCES'
+        throw error
+      }
+      return realLstat(target, options)
+    }
+    try {
+      const result = await vault.sweeper.scan()
+      assert.strictEqual(result.incomplete, true)
+    } finally {
+      fs.promises.lstat = realLstat
+    }
+
+    assert.strictEqual(vault.sweeper.state.phase, 'incomplete')
+    assert.strictEqual(vault.sweeper.state.inaccessible, 1)
+    assert.deepStrictEqual(vault.sweeper.state.inaccessible_paths, [deniedDir])
+    assert.deepStrictEqual(vault.registry.lastScan, beforeScan, 'partial counters never replace exact totals')
+    assert.strictEqual(vault.registry.links.has(deniedFile), true, 'prior record under denied subtree survives')
+    assert.strictEqual(vault.registry.links.has(accessibleFile), true, 'accessible paths are still scanned')
+
+    await vault.sweeper.scan()
+    assert.strictEqual(vault.sweeper.state.phase, 'complete')
+    assert.strictEqual(vault.sweeper.state.inaccessible, 0)
+    assert.strictEqual(vault.registry.lastScan.files, 2)
+  })
+
+  test('a failed registry write does not retain a new external source', async () => {
+    const { vault } = await makeEnv()
+    const external = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-add-rollback-'))
+    homes.push(external)
+    const realAtomicWrite = vault.registry.atomicWrite.bind(vault.registry)
+    let failed = false
+    vault.registry.atomicWrite = async (...args) => {
+      if (!failed) {
+        failed = true
+        const error = new Error('transient write failure')
+        error.code = 'EIO'
+        throw error
+      }
+      return realAtomicWrite(...args)
+    }
+    try {
+      await assert.rejects(vault.addExternalSource(external), (error) => error.code === 'EIO')
+    } finally {
+      vault.registry.atomicWrite = realAtomicWrite
+    }
+
+    assert.deepStrictEqual(vault.registry.settings.external_sources, [])
+    assert.strictEqual(vault.sources().some((source) => source.kind === 'external'), false)
+    assert.strictEqual(fs.existsSync(path.resolve(vault.root, 'sources')), false)
   })
 
   test('excluded paths are respected: no adoption, no pending, no re-listing', async () => {
@@ -166,11 +561,202 @@ describe('vault manual scan (phase 3)', () => {
     const { home, vault } = await makeEnv()
     await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), crypto.randomBytes(4096))
     await vault.sweeper.scan()
-    const after = vault.sweeper.stats.hashes
     const priorFiles = vault.registry.lastScan.files
     await vault.sweeper.scan()
-    assert.strictEqual(vault.sweeper.stats.hashes, after)
-    assert.strictEqual(vault.sweeper.state.estimated_files, priorFiles, 'same-source rescan uses the prior exact file count')
+    assert.strictEqual(vault.registry.lastScan.hashed, 0)
+    assert.strictEqual(vault.sweeper.state.total_files, priorFiles, 'every scan uses a fresh exact file count')
+  })
+
+  test('a completed scan refreshes dead names and orphan state', async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const hash = sha256(content)
+    const file = await writeFile(path.resolve(home, 'api', 'appA', 'model.bin'), content)
+    await vault.adopt(file, hash, { app: 'appA' })
+    await fs.promises.unlink(file)
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.links.has(file), false)
+    assert.strictEqual(vault.registry.blobs.get(hash).orphan, true)
+  })
+
+  test('scan-derived state is persisted once at the end of a scan', async () => {
+    const { home, vault } = await makeEnv()
+    await Promise.all(Array.from({ length: 8 }, (_, index) =>
+      writeFile(path.resolve(home, 'api', 'appA', `model-${index}.bin`), crypto.randomBytes(4096))))
+    const realFlush = vault.registry.flush.bind(vault.registry)
+    let flushes = 0
+    vault.registry.flush = async (...args) => {
+      flushes += 1
+      return realFlush(...args)
+    }
+    vault.registry.schedulePersist()
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(flushes, 1)
+  })
+
+  test('a completed scan reports a persistence warning without becoming failed', async () => {
+    const { home, vault } = await makeEnv()
+    await writeFile(path.resolve(home, 'api', 'appA', 'model.bin'), crypto.randomBytes(4096))
+    const realAtomicWrite = vault.registry.atomicWrite.bind(vault.registry)
+    vault.registry.persistDelay = 60000
+    vault.registry.atomicWrite = async () => {
+      const error = new Error('temporary snapshot write failure')
+      error.code = 'EIO'
+      throw error
+    }
+
+    try {
+      assert.deepStrictEqual(vault.startScan(), { started: true })
+      await vault.scanPromise
+      const scan = vault.scanStatus()
+      assert.strictEqual(scan.phase, 'complete')
+      assert.strictEqual(scan.error, null)
+      assert.strictEqual(scan.persistence_warning, true)
+      assert.ok(vault.registry.lastScan && vault.registry.lastScan.files === 1)
+      assert.strictEqual(vault.registry.persistDirty, true)
+    } finally {
+      vault.registry.atomicWrite = realAtomicWrite
+    }
+
+    await vault.registry.flush()
+    assert.strictEqual(vault.scanStatus().persistence_warning, false)
+  })
+
+  test('a first scan counts the exact file total before processing begins', async () => {
+    const { home, vault } = await makeEnv()
+    const dir = path.resolve(home, 'api', 'appA')
+    await Promise.all(Array.from({ length: 600 }, (_, index) =>
+      writeFile(path.resolve(dir, `small-${index}.txt`), 'x')))
+
+    const sweeper = vault.sweeper
+    const realWalk = sweeper.walk.bind(sweeper)
+    let beforeWalk = null
+    sweeper.walk = async (...args) => {
+      beforeWalk = {
+        phase: sweeper.state.phase,
+        total: sweeper.state.total_files,
+        counted: sweeper.state.counted_files
+      }
+      return realWalk(...args)
+    }
+    try {
+      await sweeper.scan()
+    } finally {
+      sweeper.walk = realWalk
+    }
+
+    assert.deepStrictEqual(beforeWalk, { phase: 'discovering', total: 600, counted: 600 })
+    assert.strictEqual(sweeper.state.files, 600)
+  })
+
+  test('a changed tree receives a new exact progress total', async () => {
+    const { home, vault } = await makeEnv()
+    const dir = path.resolve(home, 'api', 'appA')
+    await writeFile(path.resolve(dir, 'first.txt'), 'x')
+    await vault.sweeper.scan()
+    await writeFile(path.resolve(dir, 'second.txt'), 'x')
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.sweeper.state.files, 2)
+    assert.strictEqual(vault.sweeper.state.total_files, 2)
+  })
+
+  test('a stale previous scan count is never reused as the current exact progress total', async () => {
+    const { home, vault } = await makeEnv()
+    await writeFile(path.resolve(home, 'api', 'appA', 'first.txt'), 'x')
+    vault.registry.lastScan = {
+      files: 100,
+      duration_ms: 1000,
+      walk_duration_ms: 800
+    }
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.sweeper.state.files, 1)
+    assert.strictEqual(vault.sweeper.state.total_files, 1)
+  })
+
+  test('a rescan exposes its previous exact count as an approximate counting baseline', async () => {
+    const { home, vault } = await makeEnv()
+    await writeFile(path.resolve(home, 'api', 'appA', 'first.txt'), 'x')
+    vault.registry.lastScan = {
+      files: 100,
+      duration_ms: 1000,
+      count_duration_ms: 300,
+      walk_duration_ms: 600,
+      hash_wait_duration_ms: 100
+    }
+    const sweeper = vault.sweeper
+    const realCount = sweeper.countFiles.bind(sweeper)
+    let inspect
+    sweeper.countFiles = async (...args) => {
+      inspect = {
+        estimate: sweeper.state.count_estimate_files,
+        countWeight: sweeper.state.estimated_count_weight,
+        walkWeight: sweeper.state.estimated_walk_weight
+      }
+      return realCount(...args)
+    }
+    try {
+      await sweeper.scan()
+    } finally {
+      sweeper.countFiles = realCount
+    }
+
+    assert.deepStrictEqual(inspect, { estimate: 100, countWeight: 0.3, walkWeight: 0.6 })
+    assert.strictEqual(sweeper.state.total_files, 1, 'the completed current count remains exact')
+  })
+
+  test('a transient metadata failure fails the scan without replacing its last complete result', async () => {
+    const { home, vault } = await makeEnv()
+    await writeFile(path.resolve(home, 'api', 'appA', 'first.txt'), 'x')
+    await vault.sweeper.scan()
+    const before = JSON.parse(JSON.stringify(vault.registry.lastScan))
+    const unreadable = await writeFile(path.resolve(home, 'api', 'appA', 'second.txt'), 'x')
+    const realLstat = fs.promises.lstat
+    fs.promises.lstat = async (target, options) => {
+      if (path.resolve(String(target)) === unreadable) {
+        const error = new Error('temporary metadata failure')
+        error.code = 'EIO'
+        throw error
+      }
+      return realLstat(target, options)
+    }
+    try {
+      await assert.rejects(vault.sweeper.scan(), (error) => error && error.code === 'EIO')
+    } finally {
+      fs.promises.lstat = realLstat
+    }
+
+    assert.deepStrictEqual(vault.registry.lastScan, before)
+    assert.strictEqual(vault.sweeper.state.active, false)
+    assert.strictEqual(vault.sweeper.state.phase, 'failed')
+  })
+
+  test('a verification failure does not publish a completed scan timestamp', async () => {
+    const { home, vault } = await makeEnv()
+    await writeFile(path.resolve(home, 'api', 'appA', 'first.txt'), 'x')
+    await vault.sweeper.scan()
+    const before = JSON.parse(JSON.stringify(vault.registry.lastScan))
+    const realVerify = vault.verify.bind(vault)
+    vault.verify = async () => {
+      const error = new Error('temporary verification failure')
+      error.code = 'EIO'
+      throw error
+    }
+    try {
+      await assert.rejects(vault.sweeper.scan(), (error) => error && error.code === 'EIO')
+    } finally {
+      vault.verify = realVerify
+    }
+
+    assert.deepStrictEqual(vault.registry.lastScan, before)
+    assert.strictEqual(vault.sweeper.state.phase, 'failed')
   })
 
   test('file metadata inspection uses bounded concurrency without changing results', async () => {
@@ -178,32 +764,55 @@ describe('vault manual scan (phase 3)', () => {
     const dir = path.resolve(home, 'api', 'bulk')
     await Promise.all(Array.from({ length: 48 }, (_, index) =>
       writeFile(path.resolve(dir, `dir-${index}`, 'small.txt'), 'x')))
-    const realStat = fs.promises.stat
+    const realLstat = fs.promises.lstat
     let active = 0
     let maximum = 0
-    fs.promises.stat = async (target) => {
+    fs.promises.lstat = async (target) => {
       if (String(target).startsWith(dir + path.sep)) {
         active += 1
         maximum = Math.max(maximum, active)
         await new Promise((resolve) => setTimeout(resolve, 3))
         try {
-          return await realStat(target)
+          return await realLstat(target)
         } finally {
           active -= 1
         }
       }
-      return realStat(target)
+      return realLstat(target)
     }
     try {
       await vault.sweeper.scan()
     } finally {
-      fs.promises.stat = realStat
+      fs.promises.lstat = realLstat
     }
     assert.ok(maximum > 1, `expected concurrent metadata reads, saw ${maximum}`)
     assert.ok(maximum <= vault.statConcurrency, `metadata concurrency exceeded its bound: ${maximum}`)
     assert.strictEqual(vault.registry.lastScan.files >= 48, true)
   })
 
+  test('content hashing applies backpressure to keep the pending queue bounded', async () => {
+    const { home, vault } = await makeEnv()
+    await Promise.all(Array.from({ length: 8 }, (_, index) =>
+      writeFile(path.resolve(home, 'api', 'appA', `model-${index}.bin`), crypto.randomBytes(4096))))
+    vault.sweeper.hashQueueLimit = 2
+    const realHashFile = vault.hashFile.bind(vault)
+    let maximumQueued = 0
+    vault.hashFile = async (...args) => {
+      maximumQueued = Math.max(maximumQueued, vault.sweeper.state.queued)
+      await new Promise((resolve) => setTimeout(resolve, 3))
+      return realHashFile(...args)
+    }
+
+    try {
+      await vault.sweeper.scan()
+    } finally {
+      vault.hashFile = realHashFile
+    }
+
+    assert.ok(maximumQueued <= 2, `hash queue exceeded its bound: ${maximumQueued}`)
+    assert.strictEqual(vault.registry.lastScan.hashed, 8)
+  })
+
   test('multiple names for one inode share one exact hash job', async () => {
     const { home, vault } = await makeEnv()
     const content = crypto.randomBytes(4096)
@@ -221,6 +830,34 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual(vault.registry.links.get(b).hash, sha256(content))
   })
 
+  test('an inode discovered after its hash job completes reuses the completed digest', async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const a = await writeFile(path.resolve(home, 'api', 'appA', 'model.bin'), content)
+    const b = path.resolve(home, 'api', 'appB', 'model.bin')
+    await fs.promises.mkdir(path.dirname(b), { recursive: true })
+    await fs.promises.link(a, b)
+    const realConsiderStat = vault.sweeper.considerStat.bind(vault.sweeper)
+    let candidates = 0
+    vault.sweeper.considerStat = async (...args) => {
+      const result = await realConsiderStat(...args)
+      candidates += 1
+      if (candidates === 1) await vault.sweeper.settle()
+      return result
+    }
+
+    try {
+      await vault.sweeper.scan()
+    } finally {
+      vault.sweeper.considerStat = realConsiderStat
+    }
+
+    assert.strictEqual(vault.registry.lastScan.hashed, 1)
+    assert.strictEqual(vault.registry.lastScan.inode_reuses, 1)
+    assert.strictEqual(vault.registry.links.get(a).hash, sha256(content))
+    assert.strictEqual(vault.registry.links.get(b).hash, sha256(content))
+  })
+
   test('a file changed during hashing never publishes the stale digest', async () => {
     const { home, vault } = await makeEnv()
     const original = crypto.randomBytes(4096)
@@ -247,6 +884,28 @@ describe('vault manual scan (phase 3)', () => {
     assert.strictEqual((await fs.promises.stat(file)).nlink, 1, 'unstable file was not adopted')
   })
 
+  test('a file read failure aborts without publishing partial state', async () => {
+    const { home, vault } = await makeEnv()
+    const file = await writeFile(path.resolve(home, 'api', 'appA', 'unreadable.bin'), crypto.randomBytes(4096))
+    const realHashFile = vault.hashFile.bind(vault)
+    vault.hashFile = async () => {
+      const error = new Error('temporary read failure')
+      error.code = 'EIO'
+      throw error
+    }
+
+    const before = vault.registry.snapshotState()
+    try {
+      await assert.rejects(vault.sweeper.scan(), (error) => error && error.code === 'EIO')
+    } finally {
+      vault.hashFile = realHashFile
+    }
+
+    assert.strictEqual(vault.registry.lastScan, before.lastScan)
+    assert.strictEqual(vault.registry.scanIndex.has(file), false)
+    assert.strictEqual(vault.sweeper.state.phase, 'failed')
+  })
+
   test('conversion tmp files are never candidates', async () => {
     const { home, vault } = await makeEnv()
     const stray = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin.pinokio-dedup-tmp'), crypto.randomBytes(4096))
@@ -266,11 +925,262 @@ describe('vault manual scan (phase 3)', () => {
       path.resolve(dir, '.cache', 'huggingface', 'model.safetensors.metadata'),
       `commit123\n"${hash}"\n${future}\n`)
     await vault.sweeper.scan()
-    assert.strictEqual(vault.sweeper.stats.hashes, 0, 'hash harvested, not computed')
+    assert.strictEqual(vault.registry.lastScan.hashed, 0, 'hash harvested, not computed')
     assert.strictEqual((await fs.promises.stat(file)).nlink, 2)
     assert.ok(vault.registry.blobs.has(hash))
   })
 
+  test('hf --local-dir metadata older than the file always falls back to content hashing', async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const hash = sha256(content)
+    const staleHash = hash === 'a'.repeat(64) ? 'b'.repeat(64) : 'a'.repeat(64)
+    const dir = path.resolve(home, 'api', 'appA', 'ckpt')
+    const file = await writeFile(path.resolve(dir, 'model.safetensors'), content)
+    const fileStat = await fs.promises.stat(file)
+    const staleTimestamp = (fileStat.mtimeMs - 500) / 1000
+    await writeFile(
+      path.resolve(dir, '.cache', 'huggingface', 'model.safetensors.metadata'),
+      `commit123\n"${staleHash}"\n${staleTimestamp}\n`
+    )
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.lastScan.hashed, 1)
+    assert.ok(vault.registry.blobs.has(hash))
+    assert.strictEqual(vault.registry.blobs.has(staleHash), false)
+  })
+
+  test('linked hf metadata is never followed for hash-free classification', {
+    skip: process.platform === 'win32'
+  }, async () => {
+    const { home, vault } = await makeEnv()
+    const content = crypto.randomBytes(4096)
+    const actualHash = sha256(content)
+    const forgedHash = actualHash === 'a'.repeat(64) ? 'b'.repeat(64) : 'a'.repeat(64)
+    const dir = path.resolve(home, 'api', 'appA', 'ckpt')
+    await writeFile(path.resolve(dir, 'model.safetensors'), content)
+    const outside = await writeFile(path.resolve(home, 'forged.metadata'),
+      `commit123\n"${forgedHash}"\n${(Date.now() + 60000) / 1000}\n`)
+    const metadata = path.resolve(dir, '.cache', 'huggingface', 'model.safetensors.metadata')
+    await fs.promises.mkdir(path.dirname(metadata), { recursive: true })
+    await fs.promises.symlink(outside, metadata)
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.lastScan.hashed, 1)
+    assert.strictEqual(vault.registry.blobs.has(actualHash), true)
+    assert.strictEqual(vault.registry.blobs.has(forgedHash), false)
+  })
+
+  test('hash-free metadata outside an external source cannot classify its files', async () => {
+    const { vault } = await makeEnv()
+    const parent = await fs.promises.mkdtemp(path.resolve(os.tmpdir(), 'pinokio-metadata-scope-'))
+    homes.push(parent)
+    const external = path.resolve(parent, 'external')
+    const content = crypto.randomBytes(4096)
+    const actualHash = sha256(content)
+    const forgedHash = actualHash === 'a'.repeat(64) ? 'b'.repeat(64) : 'a'.repeat(64)
+    const file = await writeFile(path.resolve(external, 'model.bin'), content)
+    await writeFile(
+      path.resolve(parent, '.cache', 'huggingface', 'external', 'model.bin.metadata'),
+      `commit123\n"${forgedHash}"\n${(Date.now() + 60000) / 1000}\n`
+    )
+    await vault.addExternalSource(external)
+    const canonicalFile = path.resolve(await fs.promises.realpath(file))
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.scanIndex.get(canonicalFile).hash, actualHash)
+    assert.strictEqual(vault.registry.blobs.has(actualHash), true)
+    assert.strictEqual(vault.registry.blobs.has(forgedHash), false)
+  })
+
+  test('a changed pending path transitions to exactly one new classification', async () => {
+    const { home, vault } = await makeEnv()
+    const original = Buffer.alloc(4096, 1)
+    const changed = Buffer.alloc(4096, 2)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), original)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), original)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.keys()][0]
+
+    await fs.promises.writeFile(pending, changed)
+    const future = new Date(Date.now() + 2000)
+    await fs.promises.utimes(pending, future, future)
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.duplicates.has(pending), false)
+    assert.strictEqual(vault.registry.links.get(pending).hash, sha256(changed))
+    assert.strictEqual(vault.registry.scanIndex.get(pending).hash, sha256(changed))
+  })
+
+  test('a changed pending path updates to a different existing content group', async () => {
+    const { home, vault } = await makeEnv()
+    const first = Buffer.alloc(4096, 3)
+    const second = Buffer.alloc(4096, 4)
+    await writeFile(path.resolve(home, 'api', 'appA', 'a.bin'), first)
+    await writeFile(path.resolve(home, 'api', 'appB', 'a.bin'), first)
+    await writeFile(path.resolve(home, 'api', 'appC', 'b.bin'), second)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.keys()][0]
+
+    await fs.promises.writeFile(pending, second)
+    const future = new Date(Date.now() + 2000)
+    await fs.promises.utimes(pending, future, future)
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.links.has(pending), false)
+    assert.strictEqual(vault.registry.duplicates.get(pending).hash, sha256(second))
+    assert.strictEqual(vault.registry.scanIndex.get(pending).hash, sha256(second))
+  })
+
+  test('files below the threshold and deleted files leave no derived scan state', async () => {
+    const { home, vault } = await makeEnv()
+    const content = Buffer.alloc(4096, 5)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.keys()][0]
+    const linked = [...vault.registry.links.keys()].find((filePath) => filePath !== pending)
+
+    await fs.promises.writeFile(pending, Buffer.alloc(128, 6))
+    await fs.promises.unlink(linked)
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.duplicates.has(pending), false)
+    assert.strictEqual(vault.registry.scanIndex.has(pending), false)
+    assert.strictEqual(vault.registry.links.has(linked), false)
+    assert.strictEqual(vault.registry.scanIndex.has(linked), false)
+  })
+
+  test('raising the candidate minimum drops pending suggestions but preserves unchanged shared files', async () => {
+    const { home, vault } = await makeEnv()
+    const content = Buffer.alloc(4096, 5)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.keys()][0]
+    const linked = [...vault.registry.links.keys()].find((filePath) => filePath !== pending)
+
+    vault.sizeThreshold = 8192
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.duplicates.has(pending), false)
+    assert.strictEqual(vault.registry.scanIndex.has(pending), false)
+    assert.strictEqual(vault.registry.links.has(linked), true)
+    assert.strictEqual(vault.registry.scanIndex.has(linked), true)
+
+    await fs.promises.writeFile(linked, Buffer.alloc(128, 6))
+    await vault.sweeper.scan()
+    assert.strictEqual(vault.registry.links.get(linked).hash, sha256(Buffer.alloc(128, 6)),
+      'a file that actually changed below the minimum is still reconciled')
+  })
+
+  test('an explicit scan persists and records a validated candidate minimum', async () => {
+    const { home, vault } = await makeEnv()
+    const content = Buffer.alloc(10 * 1000 * 1000, 7)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
+
+    const invalid = await vault.perform('scan', { candidate_min_bytes: 1234 })
+    assert.match(invalid.error, /available minimum file sizes/)
+    assert.strictEqual(vault.scanPromise, undefined)
+
+    const started = await vault.perform('scan', { candidate_min_bytes: 10 * 1000 * 1000 })
+    assert.strictEqual(started.started, true)
+    await vault.scanPromise
+
+    assert.strictEqual(vault.registry.settings.candidate_min_bytes, 10 * 1000 * 1000)
+    assert.strictEqual(vault.registry.lastScan.candidate_min_bytes, 10 * 1000 * 1000)
+    assert.strictEqual(vault.registry.duplicates.size, 1)
+    const reloaded = new Registry(vault.root)
+    await reloaded.load()
+    assert.strictEqual(reloaded.settings.candidate_min_bytes, 10 * 1000 * 1000)
+  })
+
+  test('HF hash-free ingestion falls back to the generic walker for every other entry', async () => {
+    const { home, vault } = await makeEnv()
+    const blobDir = path.resolve(home, 'api', 'appA', 'cache', 'models--org--model', 'blobs')
+    const ordinary = await writeFile(path.resolve(blobDir, 'model.bin'), Buffer.alloc(4096, 7))
+    const nested = await writeFile(path.resolve(blobDir, 'nested', 'model.bin'), Buffer.alloc(4096, 8))
+
+    await vault.sweeper.scan()
+
+    assert.ok(vault.registry.scanIndex.has(ordinary))
+    assert.ok(vault.registry.scanIndex.has(nested))
+    assert.strictEqual(vault.registry.lastScan.candidates, 2)
+    assert.strictEqual(vault.registry.lastScan.hashed, 2)
+  })
+
+  test('a repaired linked inode without a trustworthy snapshot is hashed once', async () => {
+    const { home, vault } = await makeEnv()
+    const original = Buffer.alloc(4096, 10)
+    const changed = Buffer.alloc(4096, 11)
+    const file = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), original)
+    await vault.sweeper.scan()
+    const oldHash = sha256(original)
+
+    await fs.promises.writeFile(file, changed)
+    await vault.rebuild()
+    assert.strictEqual(vault.registry.scanIndex.has(file), false, 'Repair leaves changed content unverified')
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.lastScan.hashed, 1)
+    assert.strictEqual(vault.registry.blobs.has(oldHash), false)
+    assert.ok(vault.registry.blobs.has(sha256(changed)))
+    assert.strictEqual(vault.registry.scanIndex.get(file).hash, sha256(changed))
+  })
+
+  test('scan-cache identity includes the filesystem device', async () => {
+    const { home, vault } = await makeEnv()
+    const file = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), Buffer.alloc(4096, 12))
+    await vault.sweeper.scan()
+    vault.registry.scanIndex.get(file).dev = `other:${vault.registry.scanIndex.get(file).dev}`
+
+    await vault.sweeper.scan()
+
+    assert.strictEqual(vault.registry.lastScan.hashed, 1)
+  })
+
+  test('an unrelated unresolved action does not block app conversion', async () => {
+    const { home, vault, kernel } = await makeEnv()
+    const content = Buffer.alloc(4096, 13)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.values()][0]
+    kernel.api = { running: { 'custom-action-id': true } }
+
+    const pendingPath = [...vault.registry.duplicates]
+      .find(([, entry]) => entry === pending)[0]
+    const result = await vault.perform('deduplicate', {
+      scope_id: pending.source_id,
+      paths: [pendingPath]
+    })
+
+    assert.strictEqual(result.converted, 1)
+  })
+
+  test('a custom running id blocks only the app that owns its script path', async () => {
+    const { home, vault, kernel } = await makeEnv()
+    const content = Buffer.alloc(4096, 14)
+    await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
+    await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
+    await vault.sweeper.scan()
+    const pending = [...vault.registry.duplicates.values()][0]
+    const source = vault.sources().find((item) => item.id === pending.source_id)
+    kernel.api = {
+      running: { 'custom-action-id': true },
+      running_paths: { 'custom-action-id': path.resolve(source.root, 'start.js') }
+    }
+
+    const result = await vault.perform('deduplicate', { scope_id: pending.source_id })
+
+    assert.match(result.error, /running script/i)
+    assert.strictEqual(vault.registry.duplicates.size, 1)
+  })
+
   test('in-place mutation propagates to all names; scan detects divergence and evicts', async () => {
     const { home, vault } = await makeEnv()
     const original = crypto.randomBytes(4096)
@@ -294,6 +1204,97 @@ describe('vault manual scan (phase 3)', () => {
     assert.ok(events.some((e) => e.kind === 'diverged' && e.hash === oldHash))
   })
 
+  test('a fatal scan after divergence preserves the pre-scan store name and registry', async () => {
+    const { home, vault } = await makeEnv()
+    const original = crypto.randomBytes(4096)
+    const oldHash = sha256(original)
+    const a = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), original)
+    await vault.adopt(a, oldHash, { app: 'appA' })
+    const b = path.resolve(home, 'api', 'appB', 'm.bin')
+    await writeFile(b, original)
+    await vault.convert(b, oldHash, { app: 'appB' })
+    await vault.registry.flush()
+
+    await fs.promises.writeFile(b, crypto.randomBytes(4096))
+    const realVerify = vault.verify.bind(vault)
+    vault.verify = async () => {
+      const error = new Error('temporary verification failure')
+      error.code = 'EIO'
+      throw error
+    }
+    try {
+      await assert.rejects(vault.sweeper.scan(), (error) => error && error.code === 'EIO')
+    } finally {
+      vault.verify = realVerify
+    }
+
+    const [storeStat, visibleStat] = await Promise.all([
+      fs.promises.stat(vault.storePathFor(oldHash)),
+      fs.promises.stat(a)
+    ])
+    assert.strictEqual(storeStat.dev, visibleStat.dev)
+    assert.strictEqual(storeStat.ino, visibleStat.ino)
+    assert.ok(vault.registry.blobs.has(oldHash))
+    assert.strictEqual([...vault.registry.links.values()]
+      .filter((entry) => entry.hash === oldHash).length, 2)
+  })
+
+  test('partial retired-store rollback refreshes final metadata after relinking', async () => {
+    const { home, vault } = await makeEnv()
+    const first = crypto.randomBytes(4096)
+    const second = crypto.randomBytes(4096)
+    const firstPath = await writeFile(path.resolve(home, 'api', 'appA', 'first.bin'), first)
+    const secondPath = await writeFile(path.resolve(home, 'api', 'appB', 'second.bin'), second)
+    const firstHash = sha256(first)
+    const secondHash = sha256(second)
+    await vault.adopt(firstPath, firstHash, { app: 'appA' })
+    await vault.adopt(secondPath, secondHash, { app: 'appB' })
+    const firstStore = vault.storePathFor(firstHash)
+    const secondStore = vault.storePathFor(secondHash)
+    const [firstStoreStat, secondStoreStat] = await Promise.all([
+      fs.promises.stat(firstStore),
+      fs.promises.stat(secondStore)
+    ])
+    const registrySnapshot = vault.registry.snapshotState()
+
+    vault.beginScanDraft()
+    vault.rememberRetiredScanStore(firstStore, firstStoreStat, [firstPath])
+    vault.rememberRetiredScanStore(secondStore, secondStoreStat, [secondPath])
+    vault.registry.untrack(firstPath)
+    vault.registry.removeBlob(firstHash)
+    vault.registry.untrack(secondPath)
+    vault.registry.removeBlob(secondHash)
+
+    const realUnlink = fs.promises.unlink
+    let retiredUnlinks = 0
+    fs.promises.unlink = async (target) => {
+      if (target === firstStore || target === secondStore) {
+        retiredUnlinks += 1
+        if (retiredUnlinks === 2) {
+          const error = new Error('temporary store removal failure')
+          error.code = 'EIO'
+          throw error
+        }
+      }
+      return realUnlink(target)
+    }
+    try {
+      await assert.rejects(vault.commitScanDraft(), (error) => error && error.code === 'EIO')
+    } finally {
+      fs.promises.unlink = realUnlink
+    }
+
+    const restored = await fs.promises.stat(firstStore)
+    assert.strictEqual(restored.dev, firstStoreStat.dev)
+    assert.strictEqual(restored.ino, firstStoreStat.ino)
+    assert.strictEqual(await vault.abortScanDraft(registrySnapshot), true)
+    const visible = await fs.promises.stat(firstPath)
+    const indexed = vault.registry.scanIndex.get(firstPath)
+    assert.strictEqual(indexed.dev, visible.dev)
+    assert.strictEqual(indexed.ino, visible.ino)
+    assert.strictEqual(indexed.ctime, visible.ctimeMs)
+  })
+
   test('scan of a 10k-entry folder at steady state finishes fast with zero reads', async () => {
     const { home, vault } = await makeEnv()
     const dir = path.resolve(home, 'api', 'bigapp', 'stuff')
@@ -306,7 +1307,7 @@ describe('vault manual scan (phase 3)', () => {
     await vault.sweeper.scan()
     const elapsed = Date.now() - started
     assert.ok(elapsed < 2000, `steady-state rescan took ${elapsed}ms`)
-    assert.strictEqual(vault.sweeper.stats.hashes, 0)
+    assert.strictEqual(vault.registry.lastScan.hashed, 0)
   })
 
   test('locked conversions stay pending and can be retried', async () => {
@@ -316,7 +1317,14 @@ describe('vault manual scan (phase 3)', () => {
     const a = await writeFile(path.resolve(home, 'api', 'appA', 'm.bin'), content)
     await vault.adopt(a, hash, { app: 'appA' })
     const b = await writeFile(path.resolve(home, 'api', 'appB', 'm.bin'), content)
-    vault.registry.duplicates.set(b, { hash, size: content.length, app: 'appB' })
+    await vault.refreshSources()
+    const appB = vault.sources().find((source) => source.kind === 'app' && source.app === 'appB')
+    const pendingStat = await fs.promises.stat(b)
+    vault.registry.duplicates.set(b, {
+      hash, size: content.length, app: 'appB', source_id: appB.id,
+      dev: pendingStat.dev, ino: pendingStat.ino,
+      mtime: pendingStat.mtimeMs, ctime: pendingStat.ctimeMs
+    })
 
     const realConvert = vault.convert.bind(vault)
     let calls = 0
@@ -325,10 +1333,10 @@ describe('vault manual scan (phase 3)', () => {
       if (calls === 1) return { status: 'locked' }
       return realConvert(...args)
     }
-    const first = await vault.sweeper.convertPending('appB')
+    const first = await vault.perform('deduplicate', { scope_id: appB.id, paths: [b] })
     assert.strictEqual(first.locked, 1)
     assert.ok(vault.registry.duplicates.has(b), 'still pending after lock')
-    const second = await vault.sweeper.convertPending('appB')
+    const second = await vault.perform('deduplicate', { scope_id: appB.id, paths: [b] })
     vault.convert = realConvert
     assert.strictEqual(second.converted, 1)
     assert.strictEqual((await fs.promises.stat(b)).ino, (await fs.promises.stat(a)).ino)