🪜 fix: Create Missing Parents on Pathname-Only Roots So Imports Land (#360)

A root registered by path alone (--worker-dir, --workspace, --environment)
holds no descriptor, so write_file and import_file never created a missing
parent there and reported NOT_FOUND. Yet the worker advertised import_file
on every writable root, so LibreChat's first write of
.librechat/attachments/.gitignore failed on such roots and no chat upload
was ever copied.

A write or import whose parent is missing now borrows a root descriptor for
that one request and runs exactly as it does on a selected project root:
mkdirat anchored to the held fd, root ancestry checked per level, rollback
of directories an import created. A root the worker cannot hold by
descriptor is no longer advertised import_file.

Author: danny-avila

packages/code/README.md

@@ -630,6 +630,13 @@ with `--allow-workspace-writes` or
 `overwrite: false` to require an atomic create that returns `EDIT_CONFLICT` if
 the target already exists. Code API dispatches that mode only after the worker
 and server negotiate `create` in `writeFileModes`.
+`write_file` and `import_file` create missing parent directories one level at
+a time through `mkdirat` on a held root descriptor, so a swapped symlink cannot
+redirect them outside the root. Selected projects, linked-worktree lanes and
+conversation worktrees hold that descriptor for every request; a root
+registered by path alone (`--worker-dir`, `--workspace`, `--environment`) holds
+one for just the write or import whose parent is missing. A root the worker
+cannot hold by descriptor is never advertised `import_file`.
 
 `import_file` copies one stored chat upload into a writable workspace as a
 binary-safe file. It is on by default whenever the worker can perform it:
@@ -644,7 +651,7 @@ and relays a short-lived grant scoped to that object alone; the worker holds no
 storage credential. The worker applies `write_file`'s path rules, refuses any
 `.git` segment (including case, Unicode-ignorable, trailing-dot and `GIT~1`
 aliases) and symlinked parents, creates missing parents as 0755 under a held
-root, streams into a same-directory temporary file with `bytes` as a hard cap,
+root descriptor, streams into a same-directory temporary file with `bytes` as a hard cap,
 verifies size and SHA-256, syncs, and installs the file atomically with mode
 0644. Identical existing bytes return `unchanged: true` without a transfer;
 different bytes return `EDIT_CONFLICT` unless `overwrite: true`. A failure

packages/code/src/workspace-import.test.ts

@@ -258,6 +258,47 @@ test('imports binary bytes atomically into new 0755 parents as a 0644 file, what
   assert.equal(stub.hits, 1);
 });
 
+test('a pathname-only root takes chat attachments into a folder it creates, as LibreChat sends them', async (t) => {
+  const bytes = randomBytes(8192);
+  const stub = await egressStub(t, bytes);
+  const { root, tools } = await workspace(t, stub, { held: false });
+  assert.ok(tools.capabilities.workspaces[0]?.operations?.includes('import_file'));
+  const previousUmask = process.umask(0o077);
+  t.after(() => process.umask(previousUmask));
+
+  const ignore = await tools.execute({
+    protocolVersion: 1,
+    operation: 'write_file',
+    workspaceId: 'primary',
+    path: '.librechat/attachments/.gitignore',
+    content: '*\n',
+    overwrite: false,
+  });
+  assert.equal((ignore as { created: boolean }).created, true);
+  const request = importRequest(bytes, { path: '.librechat/attachments/report.pdf', overwrite: false });
+  assert.equal((await tools.execute(request) as { created: boolean }).created, true);
+  assert.deepEqual(await readFile(join(root, '.librechat', 'attachments', 'report.pdf')), bytes);
+
+  const direct = importRequest(bytes, { path: 'uploads/2026/archive.zip' });
+  assert.equal((await tools.execute(direct) as { created: boolean }).created, true);
+  assert.equal((await stat(join(root, 'uploads'))).mode & 0o777, 0o755);
+  assert.equal((await stat(join(root, 'uploads', '2026'))).mode & 0o777, 0o755);
+  assert.equal((await stat(join(root, 'uploads', '2026', 'archive.zip'))).mode & 0o777, 0o644);
+  assert.equal(stub.hits, 2);
+});
+
+test('a failed import on a pathname-only root removes the parents it created', async (t) => {
+  const stub = await egressStub(t, Buffer.from('tampered bytes'));
+  const { root, tools } = await workspace(t, stub, { held: false });
+
+  const mismatch = await rejection(
+    tools.execute(importRequest(Buffer.from('expected bytes'), { path: '.librechat/attachments/file.bin' })),
+  );
+  assert.equal(mismatch.code, 'INVALID_REQUEST');
+  assert.equal(mismatch.mutationMayHaveCommitted, false);
+  assert.deepEqual(await readdir(root), []);
+});
+
 test('re-importing identical bytes is idempotent and never downloads again', async (t) => {
   const bytes = randomBytes(4096);
   const stub = await egressStub(t, bytes);

packages/code/src/workspace.test.ts

@@ -1812,55 +1812,67 @@ test('writes create missing parent directories inside a held workspace root', as
   assert.equal((await stat(join(root, 'src', 'feature', 'deep'))).isDirectory(), true);
 });
 
-test('parent creation never follows symlinks, crosses files, or leaves the workspace', async (t) => {
-  const parent = await realpath(
-    await mkdtemp(join(tmpdir(), 'librechat-code-workspace-parent-')),
-  );
-  t.after(() => rm(parent, { recursive: true, force: true }));
-  const root = join(parent, 'root');
-  const outside = join(parent, 'outside');
-  await mkdir(join(root, 'src'), { recursive: true });
-  await mkdir(outside);
-  await writeFile(join(root, 'file.txt'), 'file');
-  await symlink(outside, join(root, 'linked-outside'));
-  await symlink(join(root, 'src'), join(root, 'alias'));
-  await symlink(join(parent, 'missing-target'), join(root, 'dangling'));
-  const tools = await heldRootTools(root);
+/** A root registered by path alone, as `--worker-dir`, `--workspace` and `--environment` do. */
+async function pathnameRootTools(root: string): Promise<LocalWorkspaceTools> {
+  return LocalWorkspaceTools.create({
+    workspaces: [{ id: 'primary', root, writable: true }],
+  });
+}
 
-  for (const [path, code] of [
-    ['linked-outside/new/notes.txt', 'INVALID_PATH'],
-    ['alias/new/notes.txt', 'INVALID_PATH'],
-    ['dangling/new/notes.txt', 'INVALID_PATH'],
-    ['file.txt/new/notes.txt', 'INVALID_PATH'],
-    ['../outside/new/notes.txt', 'INVALID_REQUEST'],
-    ['new/../../outside/notes.txt', 'INVALID_REQUEST'],
-  ] as const) {
-    await assert.rejects(
-      tools.execute({
-        protocolVersion: 1,
-        operation: 'write_file',
-        workspaceId: 'primary',
-        path,
-        content: 'blocked',
-      }),
-      (error: unknown) =>
-        error instanceof WorkspaceToolError &&
-        error.code === code &&
-        !error.mutationMayHaveCommitted,
-      path,
+for (const [kind, createTools] of [
+  ['held', heldRootTools],
+  ['pathname-only', pathnameRootTools],
+] as const) {
+  test(`parent creation never follows symlinks, crosses files, or leaves a ${kind} workspace`, async (t) => {
+    const parent = await realpath(
+      await mkdtemp(join(tmpdir(), 'librechat-code-workspace-parent-')),
     );
-  }
-  assert.deepEqual(await readdir(outside), []);
-  assert.deepEqual(await readdir(join(root, 'src')), []);
-  assert.deepEqual((await readdir(root)).sort(), [
-    'alias',
-    'dangling',
-    'file.txt',
-    'linked-outside',
-    'src',
-  ]);
-  await assert.rejects(stat(join(parent, 'missing-target')));
-});
+    t.after(() => rm(parent, { recursive: true, force: true }));
+    const root = join(parent, 'root');
+    const outside = join(parent, 'outside');
+    await mkdir(join(root, 'src'), { recursive: true });
+    await mkdir(outside);
+    await writeFile(join(root, 'file.txt'), 'file');
+    await symlink(outside, join(root, 'linked-outside'));
+    await symlink(join(root, 'src'), join(root, 'alias'));
+    await symlink(join(parent, 'missing-target'), join(root, 'dangling'));
+    const tools = await createTools(root);
+
+    for (const [path, code] of [
+      ['linked-outside/new/notes.txt', 'INVALID_PATH'],
+      ['alias/new/notes.txt', 'INVALID_PATH'],
+      ['dangling/new/notes.txt', 'INVALID_PATH'],
+      ['file.txt/new/notes.txt', 'INVALID_PATH'],
+      ['../outside/new/notes.txt', 'INVALID_REQUEST'],
+      ['new/../../outside/notes.txt', 'INVALID_REQUEST'],
+    ] as const) {
+      await assert.rejects(
+        tools.execute({
+          protocolVersion: 1,
+          operation: 'write_file',
+          workspaceId: 'primary',
+          path,
+          content: 'blocked',
+        }),
+        (error: unknown) =>
+          error instanceof WorkspaceToolError &&
+          error.code === code &&
+          !error.mutationMayHaveCommitted,
+        path,
+      );
+    }
+    assert.deepEqual(await readdir(outside), []);
+    assert.deepEqual(await readdir(join(root, 'src')), []);
+    assert.deepEqual((await readdir(root)).sort(), [
+      'alias',
+      'dangling',
+      'file.txt',
+      'linked-outside',
+      'src',
+    ]);
+    await assert.rejects(stat(join(parent, 'missing-target')));
+  });
+}
 
 test('a write finishes once it has created parents, even if cancelled', async (t) => {
   const root = await realpath(await mkdtemp(join(tmpdir(), 'librechat-code-workspace-')));
@@ -1914,12 +1926,65 @@ test('a write cancelled before creating parents leaves the workspace unchanged',
   assert.deepEqual(await readdir(root), []);
 });
 
-test('a pathname-only workspace root reports a missing parent instead of creating it', async (t) => {
-  const root = await mkdtemp(join(tmpdir(), 'librechat-code-workspace-'));
+test('a pathname-only workspace root creates missing parents like a held root', async (t) => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), 'librechat-code-workspace-')));
   t.after(() => rm(root, { recursive: true, force: true }));
-  const tools = await LocalWorkspaceTools.create({
-    workspaces: [{ id: 'primary', root, writable: true }],
-  });
+  const tools = await pathnameRootTools(root);
+
+  for (const [path, overwrite] of [
+    ['.librechat/attachments/.gitignore', false],
+    ['missing/deep/notes.txt', undefined],
+  ] as const) {
+    const result = await tools.execute({
+      protocolVersion: 1,
+      operation: 'write_file',
+      workspaceId: 'primary',
+      path,
+      content: '*\n',
+      ...(overwrite === undefined ? {} : { overwrite }),
+    });
+    assert.deepEqual(result, {
+      protocolVersion: 1,
+      operation: 'write_file',
+      workspaceId: 'primary',
+      path,
+      created: true,
+      bytesWritten: 2,
+    });
+    assert.equal(await readFile(join(root, ...path.split('/')), 'utf8'), '*\n');
+  }
+  assert.equal((await stat(join(root, '.librechat', 'attachments'))).isDirectory(), true);
+
+  await assert.rejects(
+    tools.execute({
+      protocolVersion: 1,
+      operation: 'write_file',
+      workspaceId: 'primary',
+      path: '.librechat/attachments/.gitignore',
+      content: '!keep\n',
+      overwrite: false,
+    }),
+    (error: unknown) =>
+      error instanceof WorkspaceToolError &&
+      error.code === 'EDIT_CONFLICT' &&
+      !error.mutationMayHaveCommitted,
+    'a create never replaces a file in a folder it just created',
+  );
+  assert.equal(await readFile(join(root, '.librechat', 'attachments', '.gitignore'), 'utf8'), '*\n');
+});
+
+test('a pathname-only root that has been replaced by a symlink creates nothing', async (t) => {
+  const parent = await realpath(
+    await mkdtemp(join(tmpdir(), 'librechat-code-workspace-parent-')),
+  );
+  t.after(() => rm(parent, { recursive: true, force: true }));
+  const root = join(parent, 'root');
+  const elsewhere = join(parent, 'elsewhere');
+  await mkdir(root);
+  await mkdir(elsewhere);
+  const tools = await pathnameRootTools(root);
+  await rm(root, { recursive: true });
+  await symlink(elsewhere, root);
 
   await assert.rejects(
     tools.execute({
@@ -1931,10 +1996,10 @@ test('a pathname-only workspace root reports a missing parent instead of creatin
     }),
     (error: unknown) =>
       error instanceof WorkspaceToolError &&
-      error.code === 'NOT_FOUND' &&
-      error.message === 'Workspace path does not exist',
+      error.code === 'INVALID_PATH' &&
+      !error.mutationMayHaveCommitted,
   );
-  assert.deepEqual(await readdir(root), []);
+  assert.deepEqual(await readdir(elsewhere), []);
 });
 
 test('a missing workspace path is NOT_FOUND only when reached through the workspace', async (t) => {