@@ -0,0 +1,12 @@
+---
+'@objectstack/service-storage': patch
+---
+
+fix(service-storage): the pending-upload retention no longer deletes a `pending` `sys_file` that a record or an attachment still holds
+
+Clause-②: no
+Metadata-protocol: none
+
+- **Before.** `sys_file` reaps `status: pending` rows after 7 days, through the `sys_file` reap guard. Its pending branch deleted the bytes and the row without asking whether anything held the file. A pending file can be held: until the previous release a signed-in record write could claim one (`ref_object` / `ref_id` / `ref_field` stamped while the row stayed `pending`), and a system write still does, since the seed loader writes the record before `claimFiles` commits the row. Seven days later the record named a file id whose bytes and row were gone.
+- **Now.** The pending branch asks the same hold question the tombstone branch asks (a `sys_attachment` row, or the `ref_*` columns). A held pending file is kept, bytes and row, and stays `pending`; each sweep logs one warning naming the file and its holder. An unheld pending file is reaped as before. A failure to answer the hold question keeps the file for the next sweep.
+- **What an operator does with the warning.** The uploader completes the upload with `POST /api/v1/storage/upload/complete`, which checks the stored bytes and commits the file. A record that lets go of the file hands it back to the sweep. The guard never commits the file itself, because that would skip the byte check the complete door makes.
@@ -579,6 +579,40 @@ describe('createSysFileReapGuard', () => {
     expect(confirmed).toEqual(['p1']);
   });
 
+  // [#26533] A pending file something holds is kept, on either surface, and
+  // stays pending — the guard writes nothing to it.
+  it.each([
+    ['its ref_* columns name an owner', { attachments: [] }, { ref_object: 'media', ref_id: 'm1', ref_field: 'poster' }],
+    ['a sys_attachment row holds it', { attachments: [{ id: 'a1', file_id: 'p1' }] }, {}],
+  ])('vetoes a held pending upload (%s): no byte delete, no write, one warning naming it', async (_label, seed, refs) => {
+    const engine = fakeEngine({ ...seed, files: [] });
+    const s = storage();
+    const logger = silentLogger();
+    const guard = createSysFileReapGuard(engine, () => s, logger);
+
+    const confirmed = await guard('sys_file', [{ id: 'p1', key: 'user/p1.bin', status: 'pending', ...refs }]);
+
+    expect(confirmed).toEqual([]);
+    expect(s.delete).not.toHaveBeenCalled();
+    expect(engine.updates).toEqual([]);
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+    expect(String(logger.warn.mock.calls[0][0])).toContain('sys_file p1');
+  });
+
+  it('vetoes a pending upload when the hold question cannot be answered (fail toward retention)', async () => {
+    const engine = fakeEngine({ attachments: [], files: [] });
+    engine.find = vi.fn(async () => { throw new Error('engine down'); });
+    const s = storage();
+    const logger = silentLogger();
+    const guard = createSysFileReapGuard(engine, () => s, logger);
+
+    const confirmed = await guard('sys_file', [{ id: 'p1', key: 'user/p1.bin', status: 'pending' }]);
+
+    expect(confirmed).toEqual([]);
+    expect(s.delete).not.toHaveBeenCalled();
+    expect(logger.warn).toHaveBeenCalledTimes(1);
+  });
+
   it('vetoes rows in any other state (fail toward retention)', async () => {
     const engine = fakeEngine({ attachments: [], files: [] });
     const guard = createSysFileReapGuard(engine, storage, silentLogger());
 
@@ -392,6 +392,13 @@ export async function findFileHolder(
   return hasFieldReferenceOwner(row) ? 'field-owner' : null;
 }
 
+/** Who {@link findFileHolder} found, in words an operator can look up. */
+function describeHolder(holder: Exclude<FileHolder, null>, row: Record<string, unknown>): string {
+  if (holder === 'attachment') return 'an attachment (a sys_attachment row)';
+  const field = row.ref_field != null && row.ref_field !== '' ? `.${String(row.ref_field)}` : '';
+  return `the record ${String(row.ref_object)}/${String(row.ref_id)}${field}`;
+}
+
 /**
  * The BATCHED form of {@link findFileHolder} — "which of these files is still
  * held?" — for callers holding many rows at once (commit c3c72a4bc).
@@ -582,7 +589,12 @@ async function tombstoneRefusedAttachFile(
  * (bytes reclaimed first) or vetoed (kept this sweep):
  *
  *  - `pending`: the upload was never completed; bytes may or may not exist.
- *    Best-effort byte delete, then confirm.
+ *    The same hold question first ({@link findFileHolder}): a record write
+ *    could once claim a pending file, and a system write still does (the seed
+ *    loader writes the record before `claimFiles` commits the row), so a held
+ *    pending row is the only pointer to bytes a record names. Held → veto and
+ *    warn, leaving it `pending`: committing it here would skip the byte check
+ *    `/upload/complete` makes. Unheld → best-effort byte delete, then confirm.
  *  - `deleted`: re-verify at sweep time that nothing holds the file on
  *    EITHER surface — zero `sys_attachment` join rows AND empty ownership
  *    columns (`ref_*`). Either found (hook bypass, restore, re-claim) →
@@ -636,11 +648,22 @@ export function createSysFileReapGuard(
 
       if (row.status === 'pending') {
         try {
+          const holder = await findFileHolder(engine, id, row);
+          if (holder) {
+            logger.warn(
+              `[storage] reap guard: kept pending sys_file ${id} past the pending-upload retention — ` +
+                `${describeHolder(holder, row)} still holds it, but its upload was never completed, so the ` +
+                `bytes were never checked against what the upload declared and downloads refuse it. Its ` +
+                `uploader completes it with POST /api/v1/storage/upload/complete; a record that lets go of ` +
+                `it hands it back to this sweep. Repeated each sweep until one of the two happens.`,
+            );
+            continue;
+          }
           if (storage && typeof row.key === 'string' && row.key) await storage.delete(row.key);
           confirmed.push(id);
         } catch (err) {
           logger.warn(
-            `[storage] reap guard: byte delete failed for pending sys_file ${id} (${(err as Error)?.message ?? err}); retrying next sweep`,
+            `[storage] reap guard: reclaim failed for pending sys_file ${id} (${(err as Error)?.message ?? err}); retrying next sweep`,
           );
         }
         continue;
 
@@ -0,0 +1,221 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #26533 — the pending-upload retention never reaps a file a record holds.
+ *
+ * `sys_file` declares a 7-day retention on `status: pending` rows: a presigned
+ * upload nobody completed is reclaimed, row and bytes, by the platform sweep
+ * through {@link createSysFileReapGuard}. Before #26531 a signed-in record
+ * write could claim such a file: the record kept the id, and the row was
+ * stamped with `ref_*` while it stayed `pending`. A system write still leaves
+ * that state today (the seed loader writes the record before `claimFiles`
+ * commits the row). The guard's pending branch deleted the bytes without
+ * asking whether anything held the file, so seven days later the record named
+ * an id whose bytes were gone.
+ *
+ * Now the pending branch asks the one hold question the `deleted` branch asks
+ * ({@link findFileHolder}): a held pending file is kept and named in a warning
+ * for an operator, and stays `pending` (committing it would skip the byte
+ * check `/upload/complete` makes, #24548). An unheld pending file of the same
+ * age is reaped as before.
+ *
+ * Driven as it ships: one real `ObjectQL` engine over sqlite `:memory:`,
+ * `StorageServicePlugin` booted on the local adapter (its own reap guard,
+ * registered with a real `LifecycleService`), the upload doors called as
+ * routes, and the sweep run with its clock past the retention.
+ */
+
+import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import type { RouteHandler } from '@objectstack/spec/contracts';
+import type { IStorageService } from '@objectstack/spec/contracts';
+import { RAW_FILE_VALUES_CONTEXT_KEY, type EngineQueryOptions } from '@objectstack/spec/data';
+import { ObjectQL, LifecycleService } from '@objectstack/objectql';
+import { SqlDriver } from '@objectstack/driver-sql';
+import { StorageServicePlugin } from './storage-service-plugin.js';
+import { installDefaultOrganization } from './default-organization.testkit.js';
+
+const BASE = '/api/v1/storage';
+const SYS = { isSystem: true };
+const SYS_RAW = { isSystem: true, [RAW_FILE_VALUES_CONTEXT_KEY]: true };
+const WRITER = 'u_writer';
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+const recordingLogger = () => ({
+  info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn(),
+  trace: vi.fn(), fatal: vi.fn(), child() { return this; },
+});
+
+type Res = { _status: number; _json: any };
+
+describe('#26533 — the pending-upload retention never reaps a file a record holds', () => {
+  let rootDir: string;
+  let engine: ObjectQL;
+  let lifecycle: LifecycleService;
+  let storage: IStorageService;
+  const logger = recordingLogger();
+  const routes = new Map<string, RouteHandler>();
+
+  beforeAll(async () => {
+    rootDir = join(tmpdir(), `os-26533-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    await fs.mkdir(rootDir, { recursive: true });
+
+    engine = new ObjectQL({ logger: recordingLogger() } as any);
+    engine.registerDriver(new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    }) as any, true);
+    await engine.init();
+
+    // The real engine, except that a read of an object this fixture never
+    // registered — the permission store the door's context resolution
+    // consults — answers empty.
+    const dataEngine = new Proxy(engine, {
+      get(target, prop) {
+        if (prop === 'find') {
+          return (object: string, query?: EngineQueryOptions) =>
+            target.getSchema(object) ? target.find(object, query) : Promise.resolve([]);
+        }
+        const value = Reflect.get(target, prop, target);
+        return typeof value === 'function' ? value.bind(target) : value;
+      },
+    });
+
+    // The sweep's clock stands eight days ahead: every row created below is
+    // past the 7-day pending-upload retention.
+    lifecycle = new LifecycleService({
+      getEngine: () => engine as any,
+      logger: { info: () => {}, warn: () => {}, debug: () => {} },
+      now: () => Date.now() + 8 * DAY_MS,
+      referenceAudit: { enabled: false },
+    });
+
+    const services = new Map<string, unknown>();
+    const ready: Array<() => Promise<void> | void> = [];
+    const mount = (m: string) => (path: string, handler: RouteHandler) => { routes.set(`${m}:${path}`, handler); };
+    const ctx = {
+      logger,
+      registerService: (name: string, svc: unknown) => { services.set(name, svc); },
+      getService: <T>(name: string): T => {
+        if (!services.has(name)) throw new Error(`service '${name}' not registered`);
+        return services.get(name) as T;
+      },
+      hook: (event: string, fn: () => Promise<void> | void) => { if (event === 'kernel:ready') ready.push(fn); },
+    };
+    ctx.registerService('objectql', dataEngine);
+    ctx.registerService('lifecycle', lifecycle);
+    ctx.registerService('http-server', {
+      get: mount('GET'), post: mount('POST'), put: mount('PUT'),
+      delete: vi.fn(), patch: vi.fn(), use: vi.fn(),
+      listen: vi.fn().mockResolvedValue(undefined),
+      close: vi.fn().mockResolvedValue(undefined),
+    });
+    ctx.registerService('manifest', { register: (manifest: any) => engine.registerApp(manifest) });
+    ctx.registerService('auth', {
+      api: {
+        getSession: async ({ headers }: { headers: Headers }) => {
+          const userId = headers.get('x-test-user');
+          return userId ? { user: { id: userId }, session: {} } : undefined;
+        },
+      },
+    });
+
+    const plugin = new StorageServicePlugin({ adapter: 'local', local: { rootDir }, bindToSettings: false });
+    await plugin.init(ctx as any);
+
+    engine.registerApp({
+      id: 'com.objectstack.test.pending-claimed-file-reap',
+      name: 'Pending claimed file reap',
+      version: '1.0.0',
+      type: 'plugin',
+      scope: 'system',
+      objects: [{
+        name: 'media',
+        label: 'Media',
+        fields: {
+          name: { name: 'name', type: 'text' },
+          poster: { name: 'poster', label: 'Poster', type: 'image' },
+        },
+      }],
+    } as never);
+    await engine.syncSchemas();
+    await installDefaultOrganization(engine);
+    await plugin.start(ctx as any);
+    for (const fn of ready) await fn();
+    storage = services.get('storage') as IStorageService;
+  });
+
+  afterAll(async () => {
+    try { await engine?.destroy(); } catch { /* already torn down */ }
+    if (rootDir) await fs.rm(rootDir, { recursive: true, force: true });
+  });
+
+  /** Call a storage route as the writer. */
+  const call = async (method: string, path: string, req: Record<string, unknown>): Promise<Res> => {
+    const res: any = {
+      _status: 200, _json: null,
+      json(data: any) { res._json = data; return res; },
+      send() { return res; },
+      status(code: number) { res._status = code; return res; },
+      header() { return res; },
+    };
+    const handler = routes.get(`${method}:${path}`);
+    if (!handler) throw new Error(`no route ${method} ${path}`);
+    await handler({ params: {}, query: {}, headers: { 'x-test-user': WRITER }, method, path, ...req } as any, res);
+    return res;
+  };
+
+  /** Presign, then PUT the bytes. `/upload/complete` is never called, so the row stays `pending`. */
+  const pendingUpload = async (filename: string) => {
+    const bytes = Buffer.alloc(100, 1);
+    const presigned = await call('POST', `${BASE}/upload/presigned`, {
+      body: { filename, mimeType: 'image/png', size: bytes.byteLength },
+    });
+    expect(presigned._status, JSON.stringify(presigned._json)).toBe(200);
+    const { fileId, uploadUrl } = presigned._json.data as { fileId: string; uploadUrl: string };
+    const token = uploadUrl.slice(uploadUrl.lastIndexOf('/') + 1);
+    const put = await call('PUT', `${BASE}/_local/raw/:token`, { params: { token }, rawBody: async () => bytes });
+    expect(put._status, JSON.stringify(put._json)).toBe(200);
+    return fileId;
+  };
+
+  const fileRow = async (id: string) =>
+    ((await engine.find('sys_file', { where: { id }, context: SYS })) as Array<Record<string, any>>)[0] ?? null;
+  const record = async (id: string) =>
+    ((await engine.find('media', { where: { id }, context: SYS_RAW })) as Array<Record<string, any>>)[0];
+
+  it('past the retention, a pending file a record holds keeps its bytes and row; an unheld one is reaped', async () => {
+    const claimed = await pendingUpload('claimed.png');
+    const abandoned = await pendingUpload('abandoned.png');
+    // The state a signed-in write left before #26531 (and a system write
+    // still leaves): the record holds the id, and the row carries `ref_*`
+    // while it stays `pending`.
+    await engine.insert('media', { id: 'm_1', name: 'm_1', poster: claimed } as any, { context: SYS });
+    const before = await fileRow(claimed);
+    expect(before).toMatchObject({ status: 'pending', ref_object: 'media', ref_id: 'm_1', ref_field: 'poster' });
+    const claimedKey = before!.key as string;
+    const abandonedKey = (await fileRow(abandoned))!.key as string;
+    expect(await storage.exists(claimedKey)).toBe(true);
+    expect(await storage.exists(abandonedKey)).toBe(true);
+
+    const report = await lifecycle.sweep();
+
+    expect(report.errors, JSON.stringify(report.errors)).toEqual([]);
+    // The held file: bytes and row kept, still `pending`, still owned.
+    expect(await storage.exists(claimedKey), 'the held file keeps its bytes').toBe(true);
+    expect(await fileRow(claimed)).toMatchObject({
+      status: 'pending', ref_object: 'media', ref_id: 'm_1', ref_field: 'poster',
+    });
+    expect((await record('m_1'))?.poster).toBe(claimed);
+    // Flagged for an operator, naming the file and its holder.
+    const warned = logger.warn.mock.calls.map((c) => String(c[0])).filter((line) => line.includes(claimed));
+    expect(warned).toHaveLength(1);
+    expect(warned[0]).toContain('media/m_1.poster');
+    // The unheld file of the same age: reaped, bytes and row.
+    expect(await fileRow(abandoned), 'the abandoned upload is reaped').toBeNull();
+    expect(await storage.exists(abandonedKey)).toBe(false);
+  });
+});