@aiworker/web 1.23.0 → 1.23.1

package/server/lib/opencode/env-runtime.test.js

@@ -14,6 +14,7 @@ const originalResourcesPath = process.resourcesPath;
 const originalWslBinary = process.env.WSL_BINARY;
 const originalAiWorkerWslBinary = process.env.AIWORKER_WSL_BINARY;
 const originalPlatform = process.platform;
+const originalRuntime = process.env.AIWORKER_RUNTIME;
 const tempDirs = [];
 const itIf = (condition) => condition ? it : it.skip;
 
@@ -30,6 +31,8 @@ const setPlatform = (platform) => {
 };
 
 afterEach(() => {
+  if (originalRuntime === undefined) delete process.env.AIWORKER_RUNTIME;
+  else process.env.AIWORKER_RUNTIME = originalRuntime;
   Object.defineProperty(process, 'platform', {
     value: originalPlatform,
   });
@@ -117,7 +120,76 @@ const createRuntime = (settings, options = {}) => {
   return { runtime, state };
 };
 
+const createBundledCli = () => {
+  const resourcesPath = createTempDir('openchamber-resources-');
+  const directory = path.join(resourcesPath, 'opencode-cli');
+  fs.mkdirSync(directory);
+  const binary = path.join(directory, process.platform === 'win32' ? 'opencode.exe' : 'opencode');
+  fs.writeFileSync(binary, '#!/bin/sh\nexit 0\n', { mode: 0o755 });
+  Object.defineProperty(process, 'resourcesPath', { configurable: true, value: resourcesPath });
+  return binary;
+};
+
 describe('OpenCode env runtime', () => {
+  it.each(['linux', 'darwin', 'win32'])('keeps automatic desktop bundled resolution local across relaunch on %s', (platform) => {
+    setPlatform(platform);
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+
+    const oldBinary = createBundledCli();
+    const oldRuntime = createRuntime({});
+    expect(oldRuntime.runtime.ensureOpencodeCliEnv()).toBe(oldBinary);
+    expect(oldRuntime.runtime.ensureOpencodeCliEnv()).toBe(oldBinary);
+    expect(oldRuntime.state.resolvedOpencodeBinarySource).toBe('bundled');
+    expect(process.env.OPENCODE_BINARY).toBeUndefined();
+    expect(process.env.PATH.split(path.delimiter)[0]).toBe(path.dirname(oldBinary));
+
+    // The old binary remains executable and its directory is still in PATH.
+    const newBinary = createBundledCli();
+    const newRuntime = createRuntime({});
+    expect(newRuntime.runtime.ensureOpencodeCliEnv()).toBe(newBinary);
+    expect(newRuntime.state.resolvedOpencodeBinarySource).toBe('bundled');
+    expect(newRuntime.runtime.isBundledOpenCodeCliPath(newBinary)).toBe(true);
+    expect(process.env.OPENCODE_BINARY).toBeUndefined();
+  });
+
+  it.each(['web', 'ssh-remote'])('preserves automatic binary export outside desktop in %s', (runtimeName) => {
+    process.env.AIWORKER_RUNTIME = runtimeName;
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    const { runtime } = createRuntime({});
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
+  it.each(['env', 'settings'])('preserves explicit desktop %s selection even when it points at a bundled CLI', async (source) => {
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    if (source === 'env') process.env.OPENCODE_BINARY = binary;
+    const { runtime, state } = createRuntime(source === 'settings' ? { opencodeBinary: binary } : {});
+    await runtime.applyOpencodeBinaryFromSettings({ strict: true });
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(state.resolvedOpencodeBinarySource).toBe(source);
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
+  it('preserves automatic PATH binary export for desktop without a bundled CLI', () => {
+    process.env.AIWORKER_RUNTIME = 'desktop';
+    delete process.env.OPENCODE_BINARY;
+    delete process.env.AIWORKER_BUNDLED_OPENCODE_CLI_DIR;
+    const binary = createBundledCli();
+    Object.defineProperty(process, 'resourcesPath', { configurable: true, value: undefined });
+    process.env.PATH = path.dirname(binary);
+    const { runtime, state } = createRuntime({});
+    expect(runtime.ensureOpencodeCliEnv()).toBe(binary);
+    expect(state.resolvedOpencodeBinarySource).toBe('path');
+    expect(process.env.OPENCODE_BINARY).toBe(binary);
+  });
+
   it('searches an explicit PATH without mutating the process environment', () => {
     const defaultDir = createTempDir('openchamber-default-path-');
     const explicitDir = createTempDir('openchamber-explicit-path-');

package/server/lib/opencode/feature-routes-runtime.js

@@ -307,7 +307,21 @@ export const createFeatureRoutesRuntime = (dependencies) => {
     registerSessionGoalRoutes(app);
     registerGitHubRoutes(app);
     registerLinearRoutes(app);
-    registerGitRoutes(app);
+    registerGitRoutes(app, {
+      emitWorktreeChanged: ({ directories, at }) => {
+        const clients = getAiWorkerEventClients();
+        for (const client of clients) {
+          try {
+            writeSseEvent(client, {
+              type: 'aiworker:worktree-changed',
+              properties: { directories, at },
+            });
+          } catch {
+            clients.delete(client);
+          }
+        }
+      },
+    });
     registerDevServerRoutes(app, { scanner: devServerScanner, getOwnPorts });
     registerMagicPromptRoutes(app, {
       fsPromises,

package/server/lib/opencode/lifecycle.js

@@ -377,8 +377,8 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     return parts.length > 0 ? parts.join('\n\n') : 'No stdout/stderr captured';
   };
 
-  const createManagedOpenCodeServerProcess = async ({ hostname, port, timeout, cwd, env: processEnv, shellEnvKeysCount = 0 }) => {
-    let binary = (process.env.OPENCODE_BINARY || 'opencode').trim() || 'opencode';
+  const createManagedOpenCodeServerProcess = async ({ resolvedBinary, hostname, port, timeout, cwd, env: processEnv, shellEnvKeysCount = 0 }) => {
+    let binary = (resolvedBinary || process.env.OPENCODE_BINARY || 'opencode').trim() || 'opencode';
     const sourceBinary = binary;
     let args = ['serve', '--hostname', hostname, '--port', String(port)];
     let launchWrapperType = null;
@@ -694,7 +694,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
     );
 
     await applyOpencodeBinaryFromSettings({ strict: true });
-    ensureOpencodeCliEnv();
+    const resolvedBinary = ensureOpencodeCliEnv();
     recordStartupPerformance('opencode.binary.ready', {
       attempt,
       durationMs: performance.now() - phaseStartedAt,
@@ -721,6 +721,7 @@ export const createOpenCodeLifecycleRuntime = (deps) => {
 
     try {
       const serverInstance = await createManagedOpenCodeServerProcess({
+        resolvedBinary,
         hostname: env.ENV_CONFIGURED_OPENCODE_HOSTNAME,
         port: spawnPort,
         timeout: 30000,

package/server/lib/opencode/lifecycle.test.js

@@ -126,6 +126,35 @@ const createRuntime = (overrides = {}, stateOverrides = {}, envOverrides = {}) =
 };
 
 describe('OpenCode lifecycle', () => {
+  it('uses the resolved binary directly on startup and managed restart without an env override', async () => {
+    delete process.env.OPENCODE_BINARY;
+    const binaries = ['/bundle one/opencode-cli/opencode', '/bundle two/opencode-cli/opencode'];
+    const ensureOpencodeCliEnv = vi.fn()
+      .mockReturnValueOnce(binaries[0])
+      .mockReturnValueOnce(binaries[1]);
+    spawnMock.mockImplementation(() => {
+      const child = createMockChild();
+      queueMicrotask(() => child.stdout.emit('data', 'opencode server listening on http://127.0.0.1:45678\n'));
+      return child;
+    });
+    globalThis.fetch = vi.fn(async () => ({ ok: false }));
+    const runtime = createRuntime({ ensureOpencodeCliEnv });
+    const firstServer = await runtime.startOpenCode();
+    runtime.testState.openCodeProcess = firstServer;
+    try {
+      await runtime.restartOpenCode();
+      expect(firstServer.signalCode).toBe('SIGTERM');
+      expect(spawnMock.mock.calls.map(([binary]) => binary)).toEqual(binaries);
+      expect(runtime.testState.lastOpenCodeLaunchDiagnostics.sourceBinary).toBe(binaries[1]);
+      expect(process.env.OPENCODE_BINARY).toBeUndefined();
+      for (const [, , options] of spawnMock.mock.calls) {
+        expect(options.env).not.toHaveProperty('OPENCODE_BINARY');
+      }
+    } finally {
+      await runtime.testState.openCodeProcess.close();
+    }
+  });
+
   it('records an authoritative ready terminal event for external startup', async () => {
     globalThis.fetch = vi.fn(async () => ({
       ok: true,

package/server/lib/opencode/managed-plugin-config.js

@@ -8,7 +8,7 @@ const isJsonObject = (value) => value !== null && value !== undefined && Object.
  *
  * Existing entries are preserved; an earlier entry for the same URL is dropped
  * so a restart never registers the same plugin twice. Every managed plugin
- * (agent tools, system prompt optimizer, MCP reconnect) goes through this one
+ * (agent tools, system prompt optimizer) goes through this one
  * merge so they compose in any order.
  *
  * @param {string | undefined} rawConfig the current `OPENCODE_CONFIG_CONTENT`, JSONC or unset

package/server/lib/opencode/proxy.js

@@ -11,6 +11,7 @@ import {
 import { createRealpathCache } from '../path-realpath-cache.js';
 import { DEFAULT_UPSTREAM_STALL_TIMEOUT_MS } from '../event-stream/upstream-reader.js';
 import { recordStartupPerformance } from './startup-performance.js';
+import { getWorktreeBootstrapStatus } from '../git/service.js';
 
 const DEFAULT_SSE_HEARTBEAT_INTERVAL_MS = 20_000;
 
@@ -286,6 +287,8 @@ export const registerOpenCodeProxy = (app, deps) => {
     SSE_HEARTBEAT_INTERVAL_MS = DEFAULT_SSE_HEARTBEAT_INTERVAL_MS,
     SSE_UPSTREAM_STALL_TIMEOUT_MS = DEFAULT_UPSTREAM_STALL_TIMEOUT_MS,
     getSseUpstreamStallTimeoutMs = () => SSE_UPSTREAM_STALL_TIMEOUT_MS,
+    readWorktreeBootstrapStatus = getWorktreeBootstrapStatus,
+    WORKTREE_READY_TIMEOUT_MS = 5 * 60 * 1000,
   } = deps;
 
   if (app.get('opencodeProxyConfigured')) {
@@ -775,6 +778,36 @@ export const registerOpenCodeProxy = (app, deps) => {
     }
   });
 
+  // Any directory-scoped read can initialize OpenCode's cached project/config,
+  // before session.create runs. Hold all upstream requests until Git population
+  // finishes, independently of the user's optional setup-script wait.
+  app.use('/api', async (req, res, next) => {
+    normalizeForwardedDirectoryHeaders(req.headers);
+    const url = new URL(req.url, 'http://localhost');
+    const directory = url.searchParams.get('directory') || req.get('x-opencode-directory');
+    if (!directory) return next();
+
+    const deadline = Date.now() + WORKTREE_READY_TIMEOUT_MS;
+    try {
+      while (!res.destroyed && !res.writableEnded && !req.aborted) {
+        const status = await readWorktreeBootstrapStatus(directory);
+        if (res.destroyed || res.writableEnded || req.aborted) return;
+        if (status.status === 'failed') {
+          return res.status(503).json({ error: status.error || 'Worktree bootstrap failed' });
+        }
+        if (status.status === 'ready' || status.phase === 'git-ready' || status.phase === 'setup-ready') {
+          return next();
+        }
+        if (Date.now() >= deadline) {
+          return res.status(503).json({ error: 'Timed out waiting for worktree checkout' });
+        }
+        await sleep(75);
+      }
+    } catch (error) {
+      next(error);
+    }
+  });
+
   // Windows: session merge for cross-directory session listing
   if (process.platform === 'win32') {
     app.get('/api/session', async (req, res, next) => {

package/server/lib/opencode/settings-helpers.js

@@ -473,6 +473,9 @@ export const createSettingsHelpers = (dependencies) => {
     if (candidate.sessionRetentionAction === 'archive' || candidate.sessionRetentionAction === 'delete') {
       result.sessionRetentionAction = candidate.sessionRetentionAction;
     }
+    if (typeof candidate.sessionRetentionOnlyArchived === 'boolean') {
+      result.sessionRetentionOnlyArchived = candidate.sessionRetentionOnlyArchived;
+    }
     if (candidate.tunnelBootstrapTtlMs === null) {
       result.tunnelBootstrapTtlMs = null;
     } else if (typeof candidate.tunnelBootstrapTtlMs === 'number' && Number.isFinite(candidate.tunnelBootstrapTtlMs)) {

package/server/lib/opencode/settings-helpers.test.js

@@ -690,6 +690,14 @@ describe('settings helpers', () => {
   });
 
   describe('session retention settings persistence', () => {
+    it('round-trips archived-only retention and rejects non-boolean values', () => {
+      const helpers = createTestHelpersWithRealSanitizers();
+      for (const sessionRetentionOnlyArchived of [true, false]) {
+        expect(helpers.sanitizeSettingsUpdate({ sessionRetentionOnlyArchived })).toEqual({ sessionRetentionOnlyArchived });
+      }
+      expect(helpers.sanitizeSettingsUpdate({ sessionRetentionOnlyArchived: 'true' })).toEqual({});
+      expect(helpers.sanitizeSettingsUpdate({ sessionRetentionOnlyArchived: null })).toEqual({});
+    });
     it('round-trips sessionRetentionAction archive and delete through the sanitizer', () => {
       const helpers = createTestHelpersWithRealSanitizers();
 
@@ -714,6 +722,7 @@ describe('settings helpers', () => {
         autoDeleteEnabled: true,
         autoDeleteAfterDays: 60,
         sessionRetentionAction: 'delete',
+        sessionRetentionOnlyArchived: true,
       };
 
       const sanitized = helpers.sanitizeSettingsUpdate(payload);
@@ -721,6 +730,7 @@ describe('settings helpers', () => {
       expect(sanitized.autoDeleteEnabled).toBe(true);
       expect(sanitized.autoDeleteAfterDays).toBe(60);
       expect(sanitized.sessionRetentionAction).toBe('delete');
+      expect(sanitized.sessionRetentionOnlyArchived).toBe(true);
     });
   });
 });
@@ -746,7 +756,7 @@ describe('settings registry gate', () => {
     desktopUiPassword: 'secret', githubClientId: 'client', githubScopes: 'repo', skillCatalogs: [{ id: 'c', label: 'C', source: 'https://x' }],
     defaultGitIdentityId: 'global', permissionAutoAccept: { sessions: { s: true }, revision: 1 },
     agentControlToolEnabled: true, agentWebToolEnabled: true, agentMemoryToolEnabled: true, openCodeUpdateToastDismissedVersion: '1.0.0',
-    autoDeleteEnabled: true, autoDeleteAfterDays: 30, sessionRetentionAction: 'archive', terminalShell: 'zsh', terminalLoginShells: ['zsh'],
+    autoDeleteEnabled: true, autoDeleteAfterDays: 30, sessionRetentionOnlyArchived: false, sessionRetentionAction: 'archive', terminalShell: 'zsh', terminalLoginShells: ['zsh'],
     openInAppId: 'vscode', dictationEnabled: true, sttProvider: 'local', sttServerUrl: 'http://localhost:8001/v1', sttModel: 'm', sttLocalModel: 'm', sttLanguage: 'en',
     tunnelProvider: 'cloudflare', tunnelMode: 'quick', tunnelBootstrapTtlMs: 600000, tunnelSessionTtlMs: 86400000, managedLocalTunnelConfigPath: '/tmp/x',
     managedRemoteTunnelHostname: 'x.example', managedRemoteTunnelToken: 'token', managedRemoteTunnelPresets: [{ id: 'a', name: 'A', hostname: 'a.example' }],

package/server/lib/opencode/settings-registry.json

@@ -136,6 +136,9 @@
     "autoDeleteAfterDays": {
       "scope": "instance"
     },
+    "sessionRetentionOnlyArchived": {
+      "scope": "instance"
+    },
     "sessionRetentionAction": {
       "scope": "instance"
     },

package/server/lib/opencode/settings-runtime.js

@@ -1,4 +1,4 @@
-import { createProjectIdFromPath } from '../projects/project-id.js';
+import { createProjectIdFromPath, projectConfigFileStemOf } from '../projects/project-id.js';
 import {
   buildPreferencesFields,
   flattenPreferences,
@@ -288,10 +288,10 @@ export const createSettingsRuntime = (deps) => {
       return;
     }
 
-    const oldConfigPath = path.join(PROJECTS_ROOT_DIR, `${oldId}.json`);
-    const newConfigPath = path.join(PROJECTS_ROOT_DIR, `${newId}.json`);
-    const oldStorageDir = path.join(PROJECTS_ROOT_DIR, oldId);
-    const newStorageDir = path.join(PROJECTS_ROOT_DIR, newId);
+    const oldConfigPath = path.join(PROJECTS_ROOT_DIR, `${projectConfigFileStemOf(oldId)}.json`);
+    const newConfigPath = path.join(PROJECTS_ROOT_DIR, `${projectConfigFileStemOf(newId)}.json`);
+    const oldStorageDir = path.join(PROJECTS_ROOT_DIR, projectConfigFileStemOf(oldId));
+    const newStorageDir = path.join(PROJECTS_ROOT_DIR, projectConfigFileStemOf(newId));
 
     const [oldConfig, newConfig] = await Promise.all([
       readJsonFile(oldConfigPath),
@@ -308,6 +308,28 @@ export const createSettingsRuntime = (deps) => {
     await fsPromises.rm(oldConfigPath, { force: true });
   };
 
+  /**
+   * A build before the bounded folder name created `<projectId>/` for an id
+   * the filesystem still accepted (201 to 255 characters; longer ids never
+   * got a folder). Only the bounded folder is read now, so that folder's
+   * notes, plans, and memory are moved over once. A raw name the filesystem
+   * cannot hold (ENAMETOOLONG) means no such folder ever existed.
+   */
+  const migrateRawIdStorageFolder = async (projectId) => {
+    const stem = projectConfigFileStemOf(projectId);
+    if (stem === projectId) return;
+    const rawStorageDir = path.join(PROJECTS_ROOT_DIR, projectId);
+    try {
+      await fsPromises.stat(rawStorageDir);
+    } catch (error) {
+      if (error?.code === 'ENOENT' || error?.code === 'ENAMETOOLONG') return;
+      throw error;
+    }
+    const boundedStorageDir = path.join(PROJECTS_ROOT_DIR, stem);
+    await mergeProjectContextFiles(rawStorageDir, boundedStorageDir);
+    await moveDirectoryContents(rawStorageDir, boundedStorageDir);
+  };
+
   const migrateSettingsToDeterministicProjectIds = async (current) => {
     const settings = current && typeof current === 'object' ? current : {};
     const projects = sanitizeProjects(settings.projects) || [];
@@ -328,6 +350,7 @@ export const createSettingsRuntime = (deps) => {
         await migrateProjectScopedStorage({ oldId: project.id, newId: nextId, projectPath: project.path });
         await migrateProjectIconFiles({ oldId: project.id, newId: nextId });
       }
+      await migrateRawIdStorageFolder(nextId);
       nextProjects.push({ ...project, id: nextId });
     }
 
@@ -468,19 +491,23 @@ export const createSettingsRuntime = (deps) => {
     for (const [projectId, orphansForProject] of matches.entries()) {
       const project = canonicalProjects.find((p) => p.id === projectId);
       if (!project) continue;
-      const targetPath = path.join(PROJECTS_ROOT_DIR, `${project.id}.json`);
+      const targetStem = projectConfigFileStemOf(project.id);
+      const targetPath = path.join(PROJECTS_ROOT_DIR, `${targetStem}.json`);
+      const targetStorageDir = path.join(PROJECTS_ROOT_DIR, targetStem);
 
       for (const orphan of orphansForProject) {
         const targetExisting = (await readJsonFile(targetPath)) || {};
+        // An orphan is named by the file found on disk, so its folder is the raw name.
+        const orphanStorageDir = path.join(PROJECTS_ROOT_DIR, orphan.orphanId);
         const merged = mergeProjectConfigData({
           oldConfig: orphan.content,
           newConfig: targetExisting,
-          oldStorageDir: path.join(PROJECTS_ROOT_DIR, orphan.orphanId),
-          newStorageDir: path.join(PROJECTS_ROOT_DIR, project.id),
+          oldStorageDir: orphanStorageDir,
+          newStorageDir: targetStorageDir,
           projectPath: project.path,
         });
         await writeJsonFile(targetPath, merged);
-        await moveDirectoryContents(path.join(PROJECTS_ROOT_DIR, orphan.orphanId), path.join(PROJECTS_ROOT_DIR, project.id));
+        await moveDirectoryContents(orphanStorageDir, targetStorageDir);
         await fsPromises.rm(orphan.filePath, { force: true });
         orphansConsumed.add(orphan.orphanId);
         console.log(`[projects] Recovered orphan ${orphan.orphanId} -> ${project.id} (${project.path})`);

package/server/lib/opencode/settings-runtime.test.js

@@ -1,9 +1,9 @@
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import crypto from 'crypto';
 import fsPromises from 'fs/promises';
 import os from 'os';
 import path from 'path';
-import { createProjectIdFromPath } from '../projects/project-id.js';
+import { createProjectIdFromPath, projectConfigFileStemOf } from '../projects/project-id.js';
 import { createSettingsRuntime } from './settings-runtime.js';
 
 const createRuntime = async ({ mergePersistedSettings = (_current, changes) => changes } = {}) => {
@@ -39,6 +39,20 @@ const createRuntime = async ({ mergePersistedSettings = (_current, changes) => c
 };
 
 describe('settings runtime', () => {
+  it('round-trips both archived-only retention states through instance settings', async () => {
+    const { runtime, settingsFilePath, cleanup } = await createRuntime();
+    try {
+      for (const sessionRetentionOnlyArchived of [true, false]) {
+        const settings = { sessionRetentionOnlyArchived, sessionRetentionAction: 'delete', autoDeleteAfterDays: 30 };
+        await runtime.persistSettings(settings);
+        expect(await runtime.readSettingsFromDisk()).toEqual(settings);
+        expect(JSON.parse(await fsPromises.readFile(settingsFilePath, 'utf8'))).toEqual(settings);
+      }
+    } finally {
+      await cleanup();
+    }
+  });
+
   it('uses AiWorker themes when a new install has no theme preferences', async () => {
     const { runtime, cleanup } = await createRuntime();
     try {
@@ -145,6 +159,52 @@ describe('settings runtime', () => {
     }
   });
 
+  it('migrates a legacy id into the bounded file of a project whose path is too long for a file name', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const projectPath = path.join(tempRoot, 'a'.repeat(160));
+      const oldProjectId = 'legacy-project-id';
+      const newProjectId = createProjectIdFromPath(projectPath);
+      expect(newProjectId.length).toBeGreaterThan(200);
+      const projectsRoot = path.join(path.dirname(settingsFilePath), 'projects');
+      const boundedPath = path.join(projectsRoot, `${projectConfigFileStemOf(newProjectId)}.json`);
+      expect(path.basename(boundedPath).startsWith('path_sha256_')).toBe(true);
+
+      await fsPromises.mkdir(projectPath, { recursive: true });
+      await fsPromises.mkdir(projectsRoot, { recursive: true });
+      await fsPromises.writeFile(
+        settingsFilePath,
+        JSON.stringify({
+          projects: [{ id: oldProjectId, path: projectPath, addedAt: 1, lastOpenedAt: 1 }],
+          activeProjectId: oldProjectId,
+        }, null, 2),
+        'utf8',
+      );
+      await fsPromises.writeFile(
+        path.join(projectsRoot, `${oldProjectId}.json`),
+        JSON.stringify({ 'setup-worktree': ['bun install'] }, null, 2),
+        'utf8',
+      );
+
+      const settings = await runtime.readSettingsFromDiskMigrated();
+
+      expect(settings.projects[0].id).toBe(newProjectId);
+      const migratedConfig = JSON.parse(await fsPromises.readFile(boundedPath, 'utf8'));
+      expect(migratedConfig['setup-worktree']).toEqual(['bun install']);
+      await expect(fsPromises.readFile(path.join(projectsRoot, `${oldProjectId}.json`), 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+
+      // A second pass sees the bounded file beside the settings; it is the
+      // project's own file, not a stray from the random-id era.
+      await runtime.readSettingsFromDiskMigrated();
+      expect(JSON.parse(await fsPromises.readFile(boundedPath, 'utf8'))['setup-worktree']).toEqual(['bun install']);
+      expect(warn.mock.calls.some((call) => String(call[0]).includes('orphan'))).toBe(false);
+    } finally {
+      warn.mockRestore();
+      await cleanup();
+    }
+  });
+
   it.skipIf(process.platform !== 'win32')('falls back when Windows blocks atomic settings replacement', async () => {
     const tempRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'oc-settings-runtime-'));
     const settingsFilePath = path.join(tempRoot, 'settings.json');
@@ -184,6 +244,102 @@ describe('settings runtime', () => {
     }
   });
 
+  it('moves project storage into the bounded folder when the canonical id is too long for a folder name', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      const projectPath = path.join(tempRoot, `${'segment-'.repeat(18)}`, 'demo-repo');
+      const oldProjectId = 'legacy-project-id';
+      const newProjectId = createProjectIdFromPath(projectPath);
+      const stem = projectConfigFileStemOf(newProjectId);
+      expect(newProjectId.length).toBeGreaterThan(240);
+      expect(stem).not.toBe(newProjectId);
+      const projectsRoot = path.join(path.dirname(settingsFilePath), 'projects');
+      const oldStorageDir = path.join(projectsRoot, oldProjectId);
+      const newStorageDir = path.join(projectsRoot, stem);
+
+      await fsPromises.mkdir(projectPath, { recursive: true });
+      await fsPromises.mkdir(path.join(oldStorageDir, 'plans'), { recursive: true });
+      await fsPromises.writeFile(path.join(oldStorageDir, 'context.json'), JSON.stringify({ version: 2, notes: [], todos: [{ id: 't1', text: 'keep', completed: false, createdAt: 1 }], plans: [] }), 'utf8');
+      await fsPromises.writeFile(path.join(oldStorageDir, 'plans', 'inside.md'), '# Inside\n', 'utf8');
+      await fsPromises.writeFile(path.join(oldStorageDir, 'memory.json'), JSON.stringify({ version: 1, entries: [] }), 'utf8');
+      await fsPromises.writeFile(
+        settingsFilePath,
+        JSON.stringify({
+          projects: [{ id: oldProjectId, path: projectPath, addedAt: 1, lastOpenedAt: 1 }],
+          activeProjectId: oldProjectId,
+        }, null, 2),
+        'utf8',
+      );
+      await fsPromises.writeFile(
+        path.join(projectsRoot, `${oldProjectId}.json`),
+        JSON.stringify({ projectPlanFiles: [{ id: 'inside', path: path.join(oldStorageDir, 'plans', 'inside.md') }] }, null, 2),
+        'utf8',
+      );
+
+      const settings = await runtime.readSettingsFromDiskMigrated();
+
+      expect(settings.projects.map((project) => project.id)).toEqual([newProjectId]);
+      const migratedConfig = JSON.parse(await fsPromises.readFile(path.join(projectsRoot, `${stem}.json`), 'utf8'));
+      expect(migratedConfig.projectPlanFiles).toEqual([{ id: 'inside', path: path.join(newStorageDir, 'plans', 'inside.md') }]);
+      expect(JSON.parse(await fsPromises.readFile(path.join(newStorageDir, 'context.json'), 'utf8')).todos).toHaveLength(1);
+      await fsPromises.access(path.join(newStorageDir, 'plans', 'inside.md'));
+      await fsPromises.access(path.join(newStorageDir, 'memory.json'));
+      expect((await fsPromises.readdir(projectsRoot)).sort()).toEqual([stem, `${stem}.json`]);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('moves a folder an older build created under a raw id that still fit a folder name into the bounded folder', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      // Long enough for the bounded name, short enough that an older build
+      // could still have created `<id>/` on this filesystem. The temp root
+      // differs per OS (a few characters on Linux runners, dozens on macOS),
+      // so pad to a fixed path length instead of a fixed segment.
+      const projectPathLength = 170;
+      const segment = 'x'.repeat(Math.max(1, projectPathLength - path.join(tempRoot, 'demo-repo').length - 1));
+      const projectPath = path.join(tempRoot, segment, 'demo-repo');
+      const projectId = createProjectIdFromPath(projectPath);
+      const stem = projectConfigFileStemOf(projectId);
+      expect(projectId.length).toBeGreaterThan(200);
+      expect(projectId.length).toBeLessThanOrEqual(255);
+      expect(stem).not.toBe(projectId);
+      const projectsRoot = path.join(path.dirname(settingsFilePath), 'projects');
+      const rawStorageDir = path.join(projectsRoot, projectId);
+      const boundedStorageDir = path.join(projectsRoot, stem);
+
+      await fsPromises.mkdir(projectPath, { recursive: true });
+      await fsPromises.mkdir(path.join(rawStorageDir, 'plans'), { recursive: true });
+      await fsPromises.writeFile(path.join(rawStorageDir, 'context.json'), JSON.stringify({ version: 2, notes: [{ id: 'n1', body: 'old note', createdAt: 1, updatedAt: 1 }], todos: [], plans: [] }), 'utf8');
+      await fsPromises.writeFile(path.join(rawStorageDir, 'plans', 'old.md'), '# Old\n', 'utf8');
+      await fsPromises.writeFile(path.join(rawStorageDir, 'memory.json'), JSON.stringify({ version: 1, entries: [{ id: 'm1', title: 'Old memory', body: 'x', type: 'fact', createdAt: 1, updatedAt: 1 }] }), 'utf8');
+      // The bounded folder already holds newer context: both sides survive.
+      await fsPromises.mkdir(boundedStorageDir, { recursive: true });
+      await fsPromises.writeFile(path.join(boundedStorageDir, 'context.json'), JSON.stringify({ version: 2, notes: [{ id: 'n2', body: 'new note', createdAt: 2, updatedAt: 2 }], todos: [], plans: [] }), 'utf8');
+      await fsPromises.writeFile(
+        settingsFilePath,
+        JSON.stringify({ projects: [{ id: projectId, path: projectPath, addedAt: 1, lastOpenedAt: 1 }], activeProjectId: projectId }, null, 2),
+        'utf8',
+      );
+
+      const settings = await runtime.readSettingsFromDiskMigrated();
+
+      expect(settings.projects.map((project) => project.id)).toEqual([projectId]);
+      const context = JSON.parse(await fsPromises.readFile(path.join(boundedStorageDir, 'context.json'), 'utf8'));
+      expect(context.notes.map((note) => note.id).sort()).toEqual(['n1', 'n2']);
+      await fsPromises.access(path.join(boundedStorageDir, 'plans', 'old.md'));
+      expect(JSON.parse(await fsPromises.readFile(path.join(boundedStorageDir, 'memory.json'), 'utf8')).entries).toHaveLength(1);
+      await expect(fsPromises.access(rawStorageDir)).rejects.toMatchObject({ code: 'ENOENT' });
+
+      // A second startup finds nothing left to move.
+      await runtime.readSettingsFromDiskMigrated();
+      expect(JSON.parse(await fsPromises.readFile(path.join(boundedStorageDir, 'context.json'), 'utf8')).notes).toHaveLength(2);
+    } finally {
+      await cleanup();
+    }
+  });
+
   it('cleans up orphaned settings.json.tmp files during startup migration', async () => {
     const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
     try {

package/server/lib/project-context/DOCUMENTATION.md

@@ -12,8 +12,18 @@ The managed Chats root (`~/.config/openchamber/chats`) is also one context owner
 | `<projectsDir>/<projectId>.json` | `packages/web/server/lib/projects` (`project-setup.js` for the client-owned keys behind `/api/projects/:projectId/config`; `project-config.js` for `version` / `scheduledTasks`), one write lock for both | worktree setup, draft starters, project actions, scheduled tasks |
 | `<projectsDir>/<projectId>/context.json` | **this module, exclusively** | notes, todos, plan manifest |
 | `<projectsDir>/<projectId>/plans/*.md` | **this module, exclusively** | plan bodies |
+| `<projectsDir>/<projectId>/memory.json` | `packages/web/server/lib/agent-memory` | what the agent chose to remember about the project |
 | `<repo>/<plansDir>/*.md` | this module (read, edit, delete, move) when the team config names a `plansDir`; the folder is the team's, any tool may write there | shared plan bodies |
 
+`<projectId>` in these paths is the bounded stem `projectConfigFileStemOf`
+(`packages/web/server/lib/projects/project-id.js`) gives the id: the id itself
+up to 200 characters, `path_sha256_<digest>` beyond that, so a deeply nested
+checkout gets a folder the filesystem accepts. The folder, the config file,
+and the memory file all share that one stem; nothing here composes a path from
+the raw id. The legacy-migration read below looks at the bounded config file
+for the same reason: a read of `<raw id>.json` would fail with ENAMETOOLONG
+and turn an empty project into an error.
+
 The split is the point. Both files were previously one, written by the client
 with a whole-file read-modify-write. Adding a server writer to that file would
 have made unrelated features (project actions, draft starters) clobber notes
@@ -147,9 +157,9 @@ and I/O failures are `500`.
 ## Legacy migration
 
 `projectNotes`, `projectTodos`, and `projectPlanFiles` originally lived in
-`<projectId>.json`. On the first read with no `context.json`, those three keys
-are moved out and deleted from the client-owned file; every other key is
-preserved untouched.
+`<projectId>.json` (the bounded name, see Ownership). On the first read with
+no `context.json`, those three keys are moved out and deleted from the
+client-owned file; every other key is preserved untouched.
 
 Plan links carried absolute paths. Migration converts each to a base name. A
 file already in the plans directory is used in place; one referenced from

package/server/lib/project-context/runtime.js

@@ -12,6 +12,8 @@
  * directory never invalidates a reference.
  */
 
+import { projectConfigFileStemOf } from '../projects/project-id.js';
+
 const PROJECT_CONTEXT_VERSION = 2;
 const PROJECT_NOTE_BODY_MAX_LENGTH = 3000;
 const PROJECT_NOTE_MAX_ITEMS = 200;
@@ -221,10 +223,14 @@ export const createProjectContextRuntime = (deps) => {
     return value;
   };
 
-  const storageDirFor = (projectId) => path.join(projectsDirPath, sanitizeProjectId(projectId));
+  // The folder and the client-owned config file share one bounded stem
+  // (`projectConfigFileStemOf`): an id too long for a file name would
+  // otherwise fail every read with ENAMETOOLONG instead of reading as empty.
+  const storageStemFor = (projectId) => projectConfigFileStemOf(sanitizeProjectId(projectId));
+  const storageDirFor = (projectId) => path.join(projectsDirPath, storageStemFor(projectId));
   const contextPathFor = (projectId) => path.join(storageDirFor(projectId), 'context.json');
   const plansDirFor = (projectId) => path.join(storageDirFor(projectId), 'plans');
-  const legacyConfigPathFor = (projectId) => path.join(projectsDirPath, `${sanitizeProjectId(projectId)}.json`);
+  const legacyConfigPathFor = (projectId) => path.join(projectsDirPath, `${storageStemFor(projectId)}.json`);
 
   const readJson = async (filePath) => {
     let raw;