@aiworker/web 1.22.2 → 1.23.1

package/server/lib/projects/DOCUMENTATION.md

@@ -0,0 +1,77 @@
+# Projects
+
+## Purpose
+
+Server-owned storage for a project's per-user config file,
+`~/.config/openchamber/projects/<projectId>.json`. The file holds two
+families of keys with different writers, and this module is the only place
+that writes it:
+
+| Keys | Owner | Reached through |
+|---|---|---|
+| `version`, `scheduledTasks` | `project-config.js` (scheduled-task runtime) | `/api/projects/:projectId/scheduled-tasks/*` |
+| `setup-worktree`, `setup-worktree-wait`, `projectActions`, `projectActionsPrimaryId`, `draftStarters`, `projectPath` | `project-setup.js` via `readProjectSetup` / `updateProjectSetup` on the same runtime | `GET/PUT /api/projects/:projectId/config` (`routes.js`) |
+
+Notes, todos, and plans moved out of this file to `packages/web/server/lib/project-context`.
+
+A second, optional source is the team's shared file, `<repo>/.aiworker/project.json`
+(`version: 1`; `setupWorktree`, `setupWorktreeWait`, `projectActions`, `draftStarters`,
+`plansDir`). The server reads it from the checkout the project id names
+(`projectPathFromId`). `GET /api/projects/:projectId/config`
+returns one merged view: what runs at the top level, plus `shared` and `personal`
+blocks so a page can edit the personal file without copying a teammate's entry into it.
+
+| Field | Merge rule |
+|---|---|
+| `setupWorktree` | shared first, then personal; personal `setupWorktreeMode: "replace"` uses the personal list only |
+| `setupWorktreeWait` | personal when the personal file sets it, else shared, else `false` |
+| `projectActions` | union by `id`; a personal action replaces the shared one with the same id; ids in personal `hiddenSharedActionIds` are dropped; every entry carries `source` |
+| `projectActionsPrimaryId` | personal only |
+| `draftStarters` | union by `type:name`, shared first, every entry carries `source` |
+| `plansDir` | shared only |
+
+A shared file that exists but cannot be parsed (or names a `plansDir` outside the
+repo) is `shared.status: "invalid"` with a `reason`; the personal setup is still
+served. It is never treated as "no shared setup".
+
+### Writing the shared file
+
+`PUT /api/projects/:projectId/config/shared` (`updateSharedProjectSetup`) is
+the only writer. The patch replaces the keys it names over the current file
+(a broken file counts as empty, so a write repairs it); the result is written
+pretty-printed with `version` first and only the keys that carry something
+(`serializeSharedProjectConfig`), because the file is committed and reviewed.
+A result with nothing in it removes the file and the `.aiworker` folder
+when that leaves it empty, so unsharing the last item leaves no trace. The
+write refuses a checkout that does not exist and a `plansDir` outside the
+repo. The writer has seen what it shared, so its personal trust record is set
+to the new hash; teammates still get the prompt. The shared UI composes
+"share" and "make personal" as a shared write followed by a personal write.
+
+### Trust
+
+Shared setup commands and shared actions run on the machine of whoever pulls
+the repo, so they run only after the user has seen them. The view carries
+`trust: { hash, trusted }`: `hash` is `sharedTrustHashOf(shared)`, a SHA-256
+over the executable parts (`setupWorktree` and each action's `id`, `command`,
+`runIn`, actions sorted by id; names and icons do not count), or `null` when
+nothing executes. `trusted` is true when nothing executes or the personal
+file's `sharedTrust.hash` equals the current hash, so a pull that changes a
+command brings the prompt back. The client records an answer with a PUT of
+`sharedTrustHash` (`null` forgets it). The prompt itself lives in the shared
+UI (`packages/ui/src/lib/sharedTrustConfirmation.ts`).
+
+## Modules
+
+- `project-id.js` — `createProjectIdFromPath` / `projectPathFromId`: the path-derived id (`path_<base64url>`) that names the file, and the checkout path back from it. The shared UI derives the same id (`packages/ui/src/lib/projectId.ts`); both sides must agree. `projectConfigFileStemOf`: the stem that names the file and the sibling folder for an id, see the file name invariant below.
+- `project-config.js` — `createProjectConfigRuntime`: raw read, atomic write, the cross-process file lock (Electron and a CLI `serve` can share one projects dir), scheduled-task normalization, and the project-setup read/update.
+- `project-setup.js` — sanitizers, the shared-file parser (`parseSharedProjectConfig`, `normalizePlansDir`), the merge (`mergeProjectSetup`), and the personal view for the setup keys. Mirrored in the VS Code extension host (`packages/vscode/src/project-setup.ts`), which owns the same file when the webview has no AiWorker server; keep the two in sync.
+- `routes.js` — the setup routes. `/api/projects` is on the JSON-body allowlist in `opencode/core-routes.js`.
+
+## Invariants
+
+- **Every write is a locked read-modify-write of the whole document.** Keys the writer does not own, and keys from newer builds, come back out unchanged. A setup update and a scheduled-task update never clobber each other.
+- **A wrongly shaped key is a 400, not a silent drop.** `projectSetupPatchToStored` throws; the file is untouched. Values inside a well-shaped key are sanitized (trimmed, capped, deduplicated) rather than rejected.
+- **The file name is bounded, and so is the folder beside it.** The file is `<projectId>.json` and the per-project folder is `<projectId>/` while the id is at most 200 characters. A `path_<base64url>` id grows with the checkout path, so a deeply nested project (a path of roughly 150 characters or more) would otherwise get a name beyond the 255-byte limit and every write, lock, and temp file would fail with ENAMETOOLONG. Such an id is stored as `path_sha256_<hex digest of the id>.json` instead, with the folder `path_sha256_<digest>/` beside it (`projectConfigFileStemOf`; every composer of either path goes through it: `project-config.js`, `project-context/runtime.js`, `agent-memory/runtime.js`, and the id migration and orphan recovery in `opencode/settings-runtime.js`). The digest keeps the `path_` prefix so orphan recovery skips it. A file an older build managed to write under the long name is still read when the bounded file is missing and is moved to the bounded name by the next write; a malformed one is a read failure, not an empty project. A folder an older build created under the raw id (possible only for ids of 201 to 255 characters; longer names never got one) is moved into the bounded folder once at startup, by the project id migration in `opencode/settings-runtime.js`, with `context.json` merged by entry identity when both exist. The VS Code extension host mirrors both the naming rule and the legacy read-then-move for the file (`bridge-project-setup-runtime.ts`), because a VS Code-only user has no server to do it; it never touches the folder.
+- **The client never composes the path.** `packages/ui/src/lib/openchamberConfig.ts` speaks only HTTP; the same code serves web, desktop, VS Code, and the phone, including a phone on a remote instance.
+- **`AIWORKER_DATA_DIR` moves this directory too.** Every AiWorker folder hangs off the one root; a custom root gets `projects/`, `themes/`, and `speech-models/` copied in from `~/.config/openchamber` once at startup (copied, not moved: a second instance beside the default one must not strip it) (`lib/data-dir-migration.js`). A scratch server started with its own data dir therefore never touches the real project configs.

package/server/lib/projects/project-config.js

@@ -1,6 +1,21 @@
 import { DateTime, IANAZone } from 'luxon';
 import parser from 'cron-parser';
 
+import { projectConfigFileStemOf, projectPathFromId } from './project-id.js';
+import {
+  DEFAULT_PLANS_DIR,
+  EMPTY_SHARED_PROJECT_CONFIG,
+  SHARED_CONFIG_RELATIVE_PATH,
+  applySharedProjectSetupPatch,
+  isSharedProjectConfigEmpty,
+  mergeProjectSetup,
+  parseSharedProjectConfig,
+  projectSetupPatchToStored,
+  projectSetupViewOf,
+  serializeSharedProjectConfig,
+  sharedTrustHashOf,
+} from './project-setup.js';
+
 const PROJECT_CONFIG_VERSION = 1;
 export const MAX_TASK_NAME_LENGTH = 80;
 const MAX_TASK_PROMPT_LENGTH = 20_000;
@@ -384,6 +399,15 @@ export const createProjectConfigRuntime = (deps) => {
 
   const resolveProjectConfigPath = (projectID) => {
     const safeProjectID = sanitizeProjectID(projectID);
+    return path.join(projectsDirPath, `${projectConfigFileStemOf(safeProjectID)}.json`);
+  };
+
+  // Where a build before the bounded file name stored an id too long for one
+  // (on a filesystem that still accepted it), or null when the id's own name
+  // is the current one. Read as a fallback, moved on the next write.
+  const resolveLegacyProjectConfigPath = (projectID) => {
+    const safeProjectID = sanitizeProjectID(projectID);
+    if (projectConfigFileStemOf(safeProjectID) === safeProjectID) return null;
     return path.join(projectsDirPath, `${safeProjectID}.json`);
   };
 
@@ -485,18 +509,31 @@ export const createProjectConfigRuntime = (deps) => {
     throw new Error(`timeout acquiring project config lock for ${projectID}`);
   };
 
-  const readRawProjectConfigFromDisk = async (projectID) => {
-    const filePath = resolveProjectConfigPath(projectID);
+  // The parsed document, or null when there is no file (one of
+  // `missingCodes`). Malformed JSON still throws; it is a broken file, not
+  // an empty one.
+  const readJsonDocumentIfPresent = async (filePath, missingCodes) => {
+    let raw;
     try {
-      const raw = await fsPromises.readFile(filePath, 'utf8');
-      const parsed = JSON.parse(raw);
-      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+      raw = await fsPromises.readFile(filePath, 'utf8');
     } catch (error) {
-      if (error && typeof error === 'object' && error.code === 'ENOENT') {
-        return {};
-      }
+      const code = error && typeof error === 'object' ? error.code : null;
+      if (missingCodes.includes(code)) return null;
       throw error;
     }
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+  };
+
+  // The legacy name of a long id may exceed what the filesystem can hold;
+  // ENAMETOOLONG there means "no such file". On the bounded path it would
+  // mean the projects dir itself is unusable, so it stays an error.
+  const readRawProjectConfigFromDisk = async (projectID) => {
+    const current = await readJsonDocumentIfPresent(resolveProjectConfigPath(projectID), ['ENOENT']);
+    if (current) return current;
+    const legacyPath = resolveLegacyProjectConfigPath(projectID);
+    const legacy = legacyPath ? await readJsonDocumentIfPresent(legacyPath, ['ENOENT', 'ENAMETOOLONG']) : null;
+    return legacy ?? {};
   };
 
   // Normalized tasks for reading, plus the raw on-disk record of each one for
@@ -548,26 +585,37 @@ export const createProjectConfigRuntime = (deps) => {
     })
   );
 
-  const writeProjectConfigToDisk = async (projectID, config) => {
+  // Atomic whole-document write; callers hand in the merged document so the
+  // keys they do not own survive untouched.
+  const writeRawProjectConfigToDisk = async (projectID, document) => {
     const filePath = resolveProjectConfigPath(projectID);
     const parentDirectory = path.dirname(filePath);
     const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
-    const existing = await readRawProjectConfigFromDisk(projectID);
-    const merged = {
-      ...existing,
-      version: PROJECT_CONFIG_VERSION,
-      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
-    };
-
     await fsPromises.mkdir(parentDirectory, { recursive: true });
     try {
-      await fsPromises.writeFile(temporaryPath, JSON.stringify(merged, null, 2), 'utf8');
+      await fsPromises.writeFile(temporaryPath, JSON.stringify(document, null, 2), 'utf8');
       await fsPromises.rename(temporaryPath, filePath);
     } catch (error) {
       await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
       throw error;
     }
+    // Every write goes through a read of the whole document, so the legacy
+    // file's content is now in the current one; drop it so a later read (or an
+    // older build) cannot see two copies drifting apart.
+    const legacyPath = resolveLegacyProjectConfigPath(projectID);
+    if (legacyPath) {
+      await fsPromises.rm(legacyPath, { force: true }).catch(() => {});
+    }
+  };
+
+  const writeProjectConfigToDisk = async (projectID, config) => {
+    const existing = await readRawProjectConfigFromDisk(projectID);
+    await writeRawProjectConfigToDisk(projectID, {
+      ...existing,
+      version: PROJECT_CONFIG_VERSION,
+      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
+    });
   };
 
   const withProjectWriteLock = async (projectID, mutate) => {
@@ -905,7 +953,121 @@ export const createProjectConfigRuntime = (deps) => {
     });
   };
 
+  // The client-owned part of the file (worktree setup, project actions, draft
+  // starters); see `project-setup.js`. Reads are lock-free like task lists;
+  // an update merges the sanitized patch over the raw document under the same
+  // cross-process lock the task writers use, so neither side clobbers the other.
+  // The shared file lives in the project's checkout. The checkout path comes
+  // from the id itself (`path_<base64url>`), with the personal file's
+  // `projectPath` as the fallback for ids of another form. A missing file is
+  // the normal case; an unreadable or unparsable one is reported as invalid,
+  // never as "no shared setup".
+  const projectPathOf = (projectID, personalRaw) => (
+    projectPathFromId(projectID) || (typeof personalRaw.projectPath === 'string' ? personalRaw.projectPath.trim() : '')
+  );
+  const sharedConfigPathOf = (projectPath) => path.join(projectPath, ...SHARED_CONFIG_RELATIVE_PATH.split('/'));
+
+  const readSharedProjectConfig = async (projectID, personalRaw) => {
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return { status: 'missing' };
+    let raw;
+    try {
+      raw = await fsPromises.readFile(sharedConfigPathOf(projectPath), 'utf8');
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') return { status: 'missing' };
+      return { status: 'invalid', reason: error instanceof Error ? error.message : String(error) };
+    }
+    return parseSharedProjectConfig(raw);
+  };
+
+  const mergedProjectSetupOf = async (projectID, personalRaw) => (
+    mergeProjectSetup(projectSetupViewOf(personalRaw), await readSharedProjectConfig(projectID, personalRaw))
+  );
+
+  const readProjectSetup = async (projectID) => mergedProjectSetupOf(projectID, await readRawProjectConfigFromDisk(projectID));
+
+  const updateProjectSetup = async (projectID, patch) => {
+    const stored = projectSetupPatchToStored(patch);
+    return withProjectWriteLock(projectID, async () => {
+      const existing = await readRawProjectConfigFromDisk(projectID);
+      const merged = { ...existing, ...stored };
+      for (const [key, value] of Object.entries(stored)) {
+        if (value === undefined) delete merged[key];
+      }
+      await writeRawProjectConfigToDisk(projectID, merged);
+      return mergedProjectSetupOf(projectID, merged);
+    });
+  };
+
+  /**
+   * Change the team's shared file in the checkout: the patch replaces the
+   * keys it names over the current file (a broken file counts as empty, so
+   * a write repairs it). A result with nothing in it removes the file (and
+   * the `.aiworker` folder when that leaves it empty), so unsharing the
+   * last item leaves no trace. The writer has seen the commands it just
+   * shared, so the personal trust record is set to the new hash on this
+   * instance; teammates still get the prompt.
+   */
+  const updateSharedProjectSetup = async (projectID, patch) => (
+    withProjectWriteLock(projectID, async () => {
+      const personalRaw = await readRawProjectConfigFromDisk(projectID);
+      const projectPath = projectPathOf(projectID, personalRaw);
+      if (!projectPath) throw new Error('project checkout not found');
+      try {
+        if (!(await fsPromises.stat(projectPath)).isDirectory()) throw new Error('project checkout not found');
+      } catch {
+        throw new Error('project checkout not found');
+      }
+      const currentRead = await readSharedProjectConfig(projectID, personalRaw);
+      const current = currentRead.status === 'ok' ? currentRead.config : EMPTY_SHARED_PROJECT_CONFIG;
+      const next = applySharedProjectSetupPatch(current, patch);
+
+      const filePath = sharedConfigPathOf(projectPath);
+      if (isSharedProjectConfigEmpty(next)) {
+        await fsPromises.rm(filePath, { force: true });
+        await fsPromises.rmdir(path.dirname(filePath)).catch(() => {});
+      } else {
+        await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+        const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        try {
+          await fsPromises.writeFile(temporaryPath, serializeSharedProjectConfig(next), 'utf8');
+          await fsPromises.rename(temporaryPath, filePath);
+        } catch (error) {
+          await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
+          throw error;
+        }
+      }
+
+      const hash = sharedTrustHashOf(next);
+      const personalNext = { ...personalRaw };
+      if (hash) personalNext.sharedTrust = { hash, trustedAt: Date.now() };
+      else delete personalNext.sharedTrust;
+      await writeRawProjectConfigToDisk(projectID, personalNext);
+      return mergedProjectSetupOf(projectID, personalNext);
+    })
+  );
+
+  /**
+   * The absolute repository plans folder of a project: `plansDir` from the
+   * shared file when set, else the default `.aiworker/plans`. Setting
+   * `plansDir` replaces the default outright (nothing is read from it any
+   * more); moving files between the two is the user's job. Null only when the
+   * checkout cannot be located.
+   */
+  const resolveSharedPlansDir = async (projectID) => {
+    const personalRaw = await readRawProjectConfigFromDisk(projectID);
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return null;
+    const shared = await readSharedProjectConfig(projectID, personalRaw);
+    const relative = shared.status === 'ok' && shared.config.plansDir ? shared.config.plansDir : DEFAULT_PLANS_DIR;
+    return path.join(projectPath, ...relative.split('/'));
+  };
+
   return {
+    readProjectSetup,
+    updateProjectSetup,
+    updateSharedProjectSetup,
+    resolveSharedPlansDir,
     listScheduledTasks,
     upsertScheduledTask,
     deleteScheduledTask,

package/server/lib/projects/project-config.test.js

@@ -3,6 +3,7 @@ import os from 'os';
 import path from 'path';
 import { mkdtemp, rm, readFile, writeFile } from 'fs/promises';
 import { createProjectConfigRuntime } from './project-config.js';
+import { createProjectIdFromPath } from './project-id.js';
 
 const createRuntime = async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), 'oc-scheduled-project-config-'));
@@ -175,6 +176,102 @@ describe('project-config runtime', () => {
   });
 });
 
+describe('project-config file naming', () => {
+  const nightly = {
+    name: 'nightly',
+    enabled: true,
+    schedule: { kind: 'daily', time: '09:00', timezone: 'UTC' },
+    execution: { prompt: 'run', providerID: 'openai', modelID: 'gpt-4.1' },
+  };
+
+  it('names the file by the id while the id fits a file name', async () => {
+    const { runtime, tempRoot, cleanup } = await createRuntime();
+    try {
+      const projectID = createProjectIdFromPath('/Users/someone/projects/demo');
+      expect(runtime.resolveProjectConfigPath(projectID)).toBe(path.join(tempRoot, `${projectID}.json`));
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('stores a project whose path is too long for a file name under a bounded name', async () => {
+    const { runtime, tempRoot, cleanup } = await createRuntime();
+    try {
+      // ~190 characters, like a scratchpad checkout nested under a worktree;
+      // the base64url id is longer than the 255-byte file name limit allows.
+      const projectPath = `/private/tmp/claude-501/${'segment-'.repeat(18)}/scratchpad/evidence/demo-repo`;
+      expect(projectPath.length).toBeGreaterThan(180);
+      const projectID = createProjectIdFromPath(projectPath);
+      expect(projectID.length).toBeGreaterThan(240);
+
+      const filePath = runtime.resolveProjectConfigPath(projectID);
+      const fileName = path.basename(filePath);
+      expect(path.dirname(filePath)).toBe(tempRoot);
+      expect(fileName.startsWith('path_sha256_')).toBe(true);
+      expect(fileName.length).toBeLessThan(100);
+      // The same id always maps to the same file.
+      expect(runtime.resolveProjectConfigPath(projectID)).toBe(filePath);
+
+      // The whole write path (lock file, temp file, rename) works on a real filesystem.
+      const created = await runtime.upsertScheduledTask(projectID, nightly);
+      expect(created.created).toBe(true);
+      const setup = await runtime.updateProjectSetup(projectID, { setupWorktree: ['bun install'] });
+      expect(setup.setupWorktree).toEqual(['bun install']);
+
+      const raw = JSON.parse(await readFile(filePath, 'utf8'));
+      expect(raw.scheduledTasks).toHaveLength(1);
+      expect(raw['setup-worktree']).toEqual(['bun install']);
+      expect(await runtime.listScheduledTasks(projectID)).toHaveLength(1);
+      expect((await runtime.readProjectSetup(projectID)).setupWorktree).toEqual(['bun install']);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('reads a long id from its pre-bound file name and moves it on the next write', async () => {
+    const { runtime, tempRoot, cleanup } = await createRuntime();
+    try {
+      // Long enough for the bounded name, short enough that an older build
+      // could still have written `<id>.json` on this filesystem.
+      const projectID = `path_${'a'.repeat(200)}`;
+      const legacyPath = path.join(tempRoot, `${projectID}.json`);
+      const currentPath = runtime.resolveProjectConfigPath(projectID);
+      expect(currentPath).not.toBe(legacyPath);
+      await writeFile(legacyPath, JSON.stringify({
+        version: 1,
+        scheduledTasks: [{ id: 'task-legacy', ...nightly, state: { createdAt: 1, updatedAt: 2, lastStatus: 'idle' } }],
+        projectNotes: 'keep me',
+      }), 'utf8');
+
+      const tasks = await runtime.listScheduledTasks(projectID);
+      expect(tasks.map((task) => task.id)).toEqual(['task-legacy']);
+
+      await runtime.upsertScheduledTask(projectID, { ...nightly, name: 'weekly digest' });
+
+      const raw = JSON.parse(await readFile(currentPath, 'utf8'));
+      expect(raw.scheduledTasks.map((task) => task.id)).toEqual(['task-legacy', 'task-fixed-id']);
+      expect(raw.projectNotes).toBe('keep me');
+      await expect(readFile(legacyPath, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+      expect((await runtime.listScheduledTasks(projectID)).map((task) => task.name)).toEqual(['nightly', 'weekly digest']);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('treats a malformed pre-bound file as a failure, not as an empty project', async () => {
+    const { runtime, tempRoot, cleanup } = await createRuntime();
+    try {
+      const projectID = `path_${'b'.repeat(200)}`;
+      await writeFile(path.join(tempRoot, `${projectID}.json`), '{ not json', 'utf8');
+      await expect(runtime.listScheduledTasks(projectID)).rejects.toThrow();
+      await expect(runtime.upsertScheduledTask(projectID, nightly)).rejects.toThrow();
+      await expect(readFile(runtime.resolveProjectConfigPath(projectID), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
 describe('project-config loop reconciliation', () => {
   const loop = (name, overrides = {}) => ({
     scope: 'project',

package/server/lib/projects/project-id.js

@@ -1,3 +1,11 @@
+import crypto from 'node:crypto';
+
+// The longest stem `<stem>.json` may have and still leave room, inside the
+// 255-byte file name limit, for the atomic-write `.tmp-<pid>-<ms>-<random>`
+// suffix and the `.json.lock` sibling. Ids are ASCII, so characters are bytes.
+const MAX_PROJECT_CONFIG_FILE_STEM_LENGTH = 200;
+const HASHED_PROJECT_CONFIG_FILE_STEM_PREFIX = 'path_sha256_';
+
 const normalizeProjectPathForId = (value) => {
   if (typeof value !== 'string') return '';
   return value.replace(/\\/g, '/').replace(/\/+$/g, '') || value;
@@ -11,3 +19,38 @@ export const createProjectIdFromPath = (projectPath) => {
 
   return `path_${Buffer.from(normalized, 'utf8').toString('base64url')}`;
 };
+
+/**
+ * The path a `path_<base64url>` id was made from, or `''` when the id is not
+ * of that form. The projects dir names files by this id, so the server can
+ * find the project's checkout (and the shared config inside it) from the id
+ * alone.
+ */
+export const projectPathFromId = (projectId) => {
+  if (typeof projectId !== 'string' || !projectId.startsWith('path_')) return '';
+  const encoded = projectId.slice('path_'.length);
+  if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded)) return '';
+  try {
+    return Buffer.from(encoded, 'base64url').toString('utf8');
+  } catch {
+    return '';
+  }
+};
+
+/**
+ * The stem of everything a project owns in the projects dir: the per-user
+ * config file `<projectsDir>/<stem>.json` and the sibling folder
+ * `<projectsDir>/<stem>/` (context, plans, memory). It is the id itself while
+ * that fits a file name. A `path_<base64url>` id grows with the checkout path,
+ * so a deeply nested project would otherwise get a name the filesystem
+ * rejects (ENAMETOOLONG); such an id maps to a fixed-length digest instead.
+ * The digest keeps the `path_` prefix so the orphan recovery in
+ * `opencode/settings-runtime.js` never mistakes the file for a leftover of the
+ * random-id era. The VS Code extension host applies the same rule
+ * (`packages/vscode/src/bridge-project-setup-runtime.ts`); keep the two in sync.
+ */
+export const projectConfigFileStemOf = (projectId) => {
+  if (projectId.length <= MAX_PROJECT_CONFIG_FILE_STEM_LENGTH) return projectId;
+  const digest = crypto.createHash('sha256').update(projectId, 'utf8').digest('hex');
+  return `${HASHED_PROJECT_CONFIG_FILE_STEM_PREFIX}${digest}`;
+};