@aiworker/web 1.22.2 → 1.23.1

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

@@ -1,12 +1,12 @@
-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 () => {
+const createRuntime = async ({ mergePersistedSettings = (_current, changes) => changes } = {}) => {
   const tempRoot = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'oc-settings-runtime-'));
   const settingsFilePath = path.join(tempRoot, 'settings.json');
   const runtime = createSettingsRuntime({
@@ -16,7 +16,7 @@ const createRuntime = async () => {
     SETTINGS_FILE_PATH: settingsFilePath,
     sanitizeProjects: (projects) => Array.isArray(projects) ? projects : [],
     sanitizeSettingsUpdate: (settings) => settings,
-    mergePersistedSettings: (_current, changes) => changes,
+    mergePersistedSettings,
     normalizeSettingsPaths: (settings) => ({ settings, changed: false }),
     normalizeStringArray: (values) => Array.isArray(values) ? values.filter((value) => typeof value === 'string') : [],
     formatSettingsResponse: (settings) => settings,
@@ -39,6 +39,20 @@ const createRuntime = async () => {
 };
 
 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 {
@@ -68,8 +82,8 @@ describe('settings runtime', () => {
     }
   });
 
-  it('round-trips shared sidebar preferences through settings.json', async () => {
-    const { runtime, settingsFilePath, cleanup } = await createRuntime();
+  it('round-trips shared sidebar preferences through preferences.json', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
     const preferences = {
       sidebarProjectDisplayMode: 'single',
       sidebarSessionGroupingMode: 'flat',
@@ -80,7 +94,10 @@ describe('settings runtime', () => {
       await runtime.persistSettings(preferences);
 
       await expect(runtime.readSettingsFromDisk()).resolves.toEqual(preferences);
-      await expect(fsPromises.readFile(settingsFilePath, 'utf8')).resolves.toBe(JSON.stringify(preferences, null, 2));
+      // Profile keys live in preferences.json; settings.json keeps a legacy copy for older builds.
+      expect(JSON.parse(await fsPromises.readFile(settingsFilePath, 'utf8'))).toEqual(preferences);
+      const stored = JSON.parse(await fsPromises.readFile(path.join(tempRoot, 'preferences.json'), 'utf8'));
+      expect(Object.fromEntries(Object.entries(stored.fields).map(([key, entry]) => [key, entry.value]))).toEqual(preferences);
     } finally {
       await cleanup();
     }
@@ -142,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');
@@ -181,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 {
@@ -248,3 +407,158 @@ describe('settings runtime', () => {
     }
   });
 });
+
+describe('settings runtime: preferences.json split', () => {
+  const readJson = async (filePath) => JSON.parse(await fsPromises.readFile(filePath, 'utf8'));
+
+  it('seeds preferences.json from the profile keys of an existing settings.json and leaves that file intact', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      const legacy = { projects: [], fontSize: 110, themeId: 'openchamber-dark', desktopLanAccessEnabled: true };
+      await fsPromises.writeFile(settingsFilePath, JSON.stringify(legacy));
+
+      const merged = await runtime.readSettingsFromDisk();
+      expect(merged).toMatchObject(legacy);
+
+      const preferences = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(preferences.version).toBe(1);
+      expect(Object.keys(preferences.fields).sort()).toEqual(['fontSize', 'themeId']);
+      expect(preferences.fields.fontSize.value).toBe(110);
+      expect(typeof preferences.fields.fontSize.updatedAt).toBe('number');
+      expect(await readJson(settingsFilePath)).toEqual(legacy);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('routes profile keys to preferences.json, keeps a legacy copy of them in settings.json, and drops device keys', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      await runtime.persistSettings({ fontSize: 120, desktopLanAccessEnabled: true, mobileKeyboardMode: 'native' });
+
+      const settings = await readJson(settingsFilePath);
+      expect(settings.desktopLanAccessEnabled).toBe(true);
+      // Older builds read only settings.json: the profile's base values stay there as a copy.
+      expect(settings.fontSize).toBe(120);
+      expect(settings).not.toHaveProperty('mobileKeyboardMode');
+
+      const preferences = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(preferences.fields.fontSize.value).toBe(120);
+      expect(preferences.fields).not.toHaveProperty('mobileKeyboardMode');
+      expect(preferences.fields).not.toHaveProperty('desktopLanAccessEnabled');
+
+      expect(await runtime.readSettingsFromDisk()).toMatchObject({ fontSize: 120, desktopLanAccessEnabled: true });
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('keeps the timestamp of an unchanged profile key and restamps a changed one', async () => {
+    const { runtime, tempRoot, cleanup } = await createRuntime();
+    try {
+      const preferencesPath = path.join(tempRoot, 'preferences.json');
+      await runtime.persistSettings({ fontSize: 100, padding: 100 });
+      const first = await readJson(preferencesPath);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      await runtime.persistSettings({ fontSize: 100, padding: 120 });
+      const second = await readJson(preferencesPath);
+
+      expect(second.fields.fontSize.updatedAt).toBe(first.fields.fontSize.updatedAt);
+      expect(second.fields.padding.updatedAt).toBeGreaterThan(first.fields.padding.updatedAt);
+      expect(second.fields.padding.value).toBe(120);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('treats an unreadable preferences.json as failure: no seed, no overwrite, profile writes refused, instance still served', async () => {
+    const { runtime, settingsFilePath, tempRoot, cleanup } = await createRuntime();
+    try {
+      const preferencesPath = path.join(tempRoot, 'preferences.json');
+      await fsPromises.writeFile(settingsFilePath, JSON.stringify({ desktopLanAccessEnabled: true }));
+      await fsPromises.writeFile(preferencesPath, '{ not json');
+
+      expect(await runtime.readSettingsFromDisk()).toEqual({ desktopLanAccessEnabled: true });
+
+      await runtime.persistSettings({ fontSize: 130, desktopKeepAwakeEnabled: true });
+
+      expect(await fsPromises.readFile(preferencesPath, 'utf8')).toBe('{ not json');
+      const settings = await readJson(settingsFilePath);
+      expect(settings.desktopKeepAwakeEnabled).toBe(true);
+      // The refused profile write must not land in the legacy copy either.
+      expect(settings).not.toHaveProperty('fontSize');
+    } finally {
+      await cleanup();
+    }
+  });
+});
+
+describe('settings runtime: per-surface profile keys', () => {
+  const readJson = async (filePath) => JSON.parse(await fsPromises.readFile(filePath, 'utf8'));
+  // These sequences persist several times; the default stub replaces the
+  // document with the changes, the real merge keeps the current document.
+  const createMergingRuntime = () => createRuntime({ mergePersistedSettings: (current, changes) => ({ ...current, ...changes }) });
+
+  it('stores a per-surface key under the writing surface and leaves the base alone', async () => {
+    const { runtime, tempRoot, cleanup } = await createMergingRuntime();
+    try {
+      await runtime.persistSettings({ fontSize: 100 }); // base (no surface): migrations and legacy callers
+      await runtime.persistSettings({ fontSize: 130, showReasoningTraces: false }, { surface: 'mobile' });
+
+      const stored = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(stored.fields.fontSize.value).toBe(100);
+      expect(stored.fields.fontSize.surfaces.mobile.value).toBe(130);
+      // Not per-surface: written to the base regardless of the surface.
+      expect(stored.fields.showReasoningTraces.value).toBe(false);
+      expect(stored.fields.showReasoningTraces.surfaces).toBeUndefined();
+
+      expect((await runtime.readSettingsFromDisk({ surface: 'mobile' })).fontSize).toBe(130);
+      expect((await runtime.readSettingsFromDisk({ surface: 'desktop' })).fontSize).toBe(100);
+      expect((await runtime.readSettingsFromDisk()).fontSize).toBe(100);
+      expect((await runtime.readSettingsFromDiskMigrated({ surface: 'mobile' })).fontSize).toBe(130);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('a per-surface key set only from one surface has no base and stays absent elsewhere', async () => {
+    const { runtime, tempRoot, cleanup } = await createMergingRuntime();
+    try {
+      await runtime.persistSettings({ stickyUserHeader: false }, { surface: 'mobile' });
+      const stored = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(stored.fields.stickyUserHeader).not.toHaveProperty('value');
+      expect(stored.fields.stickyUserHeader.surfaces.mobile.value).toBe(false);
+      expect((await runtime.readSettingsFromDisk({ surface: 'desktop' })).stickyUserHeader).toBeUndefined();
+      expect((await runtime.readSettingsFromDisk({ surface: 'mobile' })).stickyUserHeader).toBe(false);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('a surface write of an unrelated key does not copy the resolved per-surface view into the file', async () => {
+    const { runtime, tempRoot, cleanup } = await createMergingRuntime();
+    try {
+      await runtime.persistSettings({ fontSize: 100 });
+      await runtime.persistSettings({ fontSize: 130 }, { surface: 'mobile' });
+      await runtime.persistSettings({ showReasoningTraces: true }, { surface: 'mobile' });
+      const stored = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(stored.fields.fontSize.value).toBe(100);
+      expect(stored.fields.fontSize.surfaces.mobile.value).toBe(130);
+      expect(stored.fields.fontSize.surfaces.desktop).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('ignores an unknown surface header value and writes the base', async () => {
+    const { runtime, tempRoot, cleanup } = await createMergingRuntime();
+    try {
+      await runtime.persistSettings({ fontSize: 90 }, { surface: 'toaster' });
+      const stored = await readJson(path.join(tempRoot, 'preferences.json'));
+      expect(stored.fields.fontSize.value).toBe(90);
+      expect(stored.fields.fontSize.surfaces).toBeUndefined();
+    } finally {
+      await cleanup();
+    }
+  });
+});

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

@@ -9,9 +9,20 @@ The managed Chats root (`~/.config/openchamber/chats`) is also one context owner
 
 | Path | Owner | Contents |
 |---|---|---|
-| `<projectsDir>/<projectId>.json` | shared UI (`packages/ui/src/lib/openchamberConfig.ts`), plus server-owned `version` / `scheduledTasks` | worktree setup, draft starters, project actions |
+| `<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
@@ -58,6 +69,27 @@ denormalized into the manifest so listing plans costs one read rather than one
 read per plan; `readPlan` returns the title parsed from the file, which wins if
 the two ever disagree.
 
+## Shared plans
+
+Every `.md` file in the repository plans folder is a plan too: `.aiworker/plans`
+by default, or the `plansDir` the team config (`<repo>/.aiworker/project.json`,
+see `packages/web/server/lib/projects`) names instead of it (the custom folder
+replaces the default outright; moving files between the two is the user's job). `readContext` appends them after the personal ones,
+each marked `source: "shared"` (personal ones get `source: "personal"`), and
+reports the folder as `sharedPlansDir`. A shared plan is addressed as
+`shared:<file>` when no manifest entry claims it; its title is parsed from the
+file on every list, and `readPlan` / `updatePlan` / `deletePlan` work on the
+file directly (an update writes the raw document verbatim, so a plan another
+tool wrote keeps its shape). `setPlanPinned` is `404` for such a plan.
+
+A plan the user moves there keeps its id: `sharePlan` moves the markdown into
+the folder and keeps the manifest entry with `shared: true` (the flag says
+which folder holds the file), so a session that attached the plan still finds
+it, and the file is listed under that id instead of `shared:<file>`.
+`unsharePlan` moves it back and clears the flag; a plan that only ever lived
+in the team's folder gets a manifest entry (and an id) on the way in. A name
+collision gets a numeric suffix. Sharing is refused only when the checkout cannot be located.
+
 ## Routes
 
 | Method | Route | Notes |
@@ -72,6 +104,8 @@ the two ever disagree.
 | POST | `/api/project-context/:projectId/plans` | `201`; takes `{title, body}`, never a path |
 | PUT | `/api/project-context/:projectId/plans/:planId` | takes the whole `{raw}` document; `404` when the link or its markdown is gone |
 | DELETE | `/api/project-context/:projectId/plans/:planId` | `404` when unknown |
+| POST | `/api/project-context/:projectId/plans/:planId/share` | moves the plan into the shared folder; `400` without one, `404` when unknown |
+| POST | `/api/project-context/:projectId/plans/:planId/unshare` | moves a `shared:` plan back; `404` when unknown |
 
 **Body parsing is attached per route.** This server has no global JSON parser:
 `core-routes` parses only an allowlist of `/api` path prefixes so the generic
@@ -123,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/routes.http.test.js

@@ -57,6 +57,8 @@ const createApp = (overrides = {}) => {
       context: emptyContext,
     }),
     deletePlan: async () => ({ deleted: true, context: emptyContext }),
+    sharePlan: async (_projectId, planId) => (planId === 'p1' ? { plan: { id: 'shared:a.md', file: 'a.md', title: 'A', createdAt: 1, pinned: false, source: 'shared' }, context: emptyContext } : null),
+    unsharePlan: async (_projectId, planId) => (planId === 'shared:a.md' ? { plan: { id: 'p2', file: 'a.md', title: 'A', createdAt: 1, pinned: false, source: 'personal' }, context: emptyContext } : null),
     ...overrides,
   };
 
@@ -212,6 +214,22 @@ describe('project context routes over HTTP', () => {
       .expect(400);
   });
 
+  it('shares and unshares a plan, and answers 404 for an unknown one', async () => {
+    const { app } = createApp();
+    const shared = await request(app).post('/api/project-context/proj/plans/p1/share');
+    expect(shared.status).toBe(200);
+    expect(shared.body.plan.id).toBe('shared:a.md');
+    const back = await request(app).post('/api/project-context/proj/plans/shared%3Aa.md/unshare');
+    expect(back.status).toBe(200);
+    expect(back.body.plan.source).toBe('personal');
+    expect((await request(app).post('/api/project-context/proj/plans/nope/share')).status).toBe(404);
+  });
+
+  it('answers 400 when sharing without a shared plans folder', async () => {
+    const { app } = createApp({ sharePlan: async () => { throw new Error('shared plans folder is required'); } });
+    expect((await request(app).post('/api/project-context/proj/plans/p1/share')).status).toBe(400);
+  });
+
   it('returns 404 for an unknown plan', async () => {
     const { app } = createApp();
     await request(app).get(`${BASE}/plans/nope`).expect(404);

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

@@ -220,6 +220,21 @@ export const registerProjectContextRoutes = (app, dependencies) => {
     }
   });
 
+  // Moving a plan between the user's folder and the team's shared folder.
+  for (const [suffix, method] of [['share', 'sharePlan'], ['unshare', 'unsharePlan']]) {
+    app.post(`/api/project-context/:projectId/plans/:planId/${suffix}`, async (req, res) => {
+      try {
+        const result = await projectContextRuntime[method](req.params.projectId, req.params.planId);
+        if (!result) {
+          return res.status(404).json({ error: 'Plan not found' });
+        }
+        return res.json(result);
+      } catch (error) {
+        return respondWithError(res, error, `Failed to ${suffix} plan`);
+      }
+    });
+  }
+
   app.delete('/api/project-context/:projectId/plans/:planId', async (req, res) => {
     try {
       const { deleted, context } = await projectContextRuntime.deletePlan(