@aiworker/web 1.22.2 → 1.23.0

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

@@ -1,4 +1,18 @@
 import { createProjectIdFromPath } from '../projects/project-id.js';
+import {
+  buildPreferencesFields,
+  flattenPreferences,
+  instancePartOf,
+  legacySettingsDocumentOf,
+  profilePartOf,
+  isDeviceSettingsKey,
+  isProfileSettingsKey,
+  normalizeSettingsSurface,
+  parsePreferencesDocument,
+  preferencesFilePathFor,
+  seedPreferencesFrom,
+  serializePreferencesDocument,
+} from './settings-files.js';
 
 const DEFAULT_NOTIFICATION_TEMPLATES = {
   completion: { title: '{agent_name} is ready', message: '{model_name} completed the task' },
@@ -48,6 +62,13 @@ export const createSettingsRuntime = (deps) => {
 
   let persistSettingsLock = Promise.resolve();
 
+  const PREFERENCES_FILE_PATH = preferencesFilePathFor(SETTINGS_FILE_PATH, path);
+  // True while preferences.json exists but cannot be read. Profile writes are
+  // refused meanwhile so a corrupt file is never overwritten with a seed or a
+  // partial document; clients keep the values they hold.
+  let preferencesUnavailable = false;
+  let preferencesFailureLogged = false;
+
   // Orphan recovery is a one-shot best-effort scan: when orphans can't be
   // matched on first pass they stay on disk and every subsequent settings
   // read would re-scan them. In-process (Electron) this runs in the main
@@ -472,7 +493,7 @@ export const createSettingsRuntime = (deps) => {
     }
   };
 
-  const readSettingsFromDisk = async () => {
+  const readInstanceSettingsFromDisk = async () => {
     try {
       const raw = await fsPromises.readFile(SETTINGS_FILE_PATH, 'utf8');
       const parsed = JSON.parse(raw);
@@ -489,6 +510,67 @@ export const createSettingsRuntime = (deps) => {
     }
   };
 
+  /**
+   * `{ status: 'missing' }` when the file does not exist, `{ status: 'ok',
+   * fields }` when it parsed, `{ status: 'failed' }` for anything else. Only
+   * "missing" may be seeded; "failed" must leave the file alone.
+   */
+  const readPreferenceFields = async () => {
+    let raw;
+    try {
+      raw = await fsPromises.readFile(PREFERENCES_FILE_PATH, 'utf8');
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') {
+        return { status: 'missing' };
+      }
+      if (!preferencesFailureLogged) {
+        preferencesFailureLogged = true;
+        console.warn('Failed to read preferences file:', error);
+      }
+      return { status: 'failed' };
+    }
+    const parsed = parsePreferencesDocument(raw);
+    if (!parsed.ok) {
+      if (!preferencesFailureLogged) {
+        preferencesFailureLogged = true;
+        console.warn(`Preferences file is unreadable (${parsed.reason}); profile writes are paused until it is fixed or removed.`);
+      }
+      return { status: 'failed' };
+    }
+    preferencesFailureLogged = false;
+    return { status: 'ok', fields: parsed.fields };
+  };
+
+  const writePreferencesToDisk = async (fields) => {
+    await writeJsonFileAtomic(PREFERENCES_FILE_PATH, serializePreferencesDocument(fields));
+  };
+
+  // The merged document every consumer sees: instance facts from settings.json
+  // plus the profile from preferences.json. On the first read of an install
+  // that predates the split, the profile keys still sitting in settings.json
+  // seed preferences.json. settings.json keeps a copy of the profile's base
+  // values on every write too, so an older build (which reads only that file)
+  // still finds everything where it used to be.
+  const readSettingsFromDisk = async ({ surface = null } = {}) => {
+    const instance = await readInstanceSettingsFromDisk();
+    const preferences = await readPreferenceFields();
+    if (preferences.status === 'failed') {
+      preferencesUnavailable = true;
+      return instance;
+    }
+    preferencesUnavailable = false;
+    if (preferences.status === 'missing') {
+      const seeded = seedPreferencesFrom(instance, Date.now());
+      try {
+        await writePreferencesToDisk(seeded);
+      } catch (error) {
+        console.warn('Failed to seed preferences file:', error);
+      }
+      return instance;
+    }
+    return { ...instance, ...flattenPreferences(preferences.fields, normalizeSettingsSurface(surface)) };
+  };
+
   // Strict variant for callers that REGENERATE persisted identity when a key is
   // absent (relay signing/encryption keys). The lenient reader above maps every
   // failure — corrupt JSON, EACCES, transient I/O — to `{}`, which such callers
@@ -558,7 +640,7 @@ export const createSettingsRuntime = (deps) => {
     try {
       const entries = await fsPromises.readdir(directory, { withFileTypes: true });
       const cleanupTasks = entries
-        .filter((entry) => entry.isFile() && entry.name.startsWith('settings.json.tmp-'))
+        .filter((entry) => entry.isFile() && (entry.name.startsWith('settings.json.tmp-') || entry.name.startsWith('preferences.json.tmp-')))
         .map((entry) => fsPromises.rm(path.join(directory, entry.name), { force: true }).catch(() => {}));
       await Promise.all(cleanupTasks);
     } catch {
@@ -566,27 +648,54 @@ export const createSettingsRuntime = (deps) => {
     }
   };
 
-  const writeSettingsToDisk = async (settings) => {
-    const settingsDirectory = path.dirname(SETTINGS_FILE_PATH);
-    await fsPromises.mkdir(settingsDirectory, { recursive: true, mode: 0o700 });
-    if (process.platform !== 'win32') await fsPromises.chmod(settingsDirectory, 0o700);
-    // Atomic write: Electron main and ssh-manager read this file via plain
+  const writeJsonFileAtomic = async (filePath, text) => {
+    const directory = path.dirname(filePath);
+    await fsPromises.mkdir(directory, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32') await fsPromises.chmod(directory, 0o700);
+    // Atomic write: Electron main and ssh-manager read these files via plain
     // readFile + JSON.parse and silently coerce parse errors to {}. A
     // partial read during a non-atomic writeFile would make their next
-    // read-modify-write wipe the settings file.
-    const tmp = `${SETTINGS_FILE_PATH}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    // read-modify-write wipe the file.
+    const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     try {
-      await fsPromises.writeFile(tmp, JSON.stringify(settings, null, 2), { encoding: 'utf8', mode: 0o600 });
+      await fsPromises.writeFile(tmp, text, { encoding: 'utf8', mode: 0o600 });
       if (process.platform !== 'win32') await fsPromises.chmod(tmp, 0o600);
-      await replaceFile(tmp, SETTINGS_FILE_PATH);
-      if (process.platform !== 'win32') await fsPromises.chmod(SETTINGS_FILE_PATH, 0o600);
+      await replaceFile(tmp, filePath);
+      if (process.platform !== 'win32') await fsPromises.chmod(filePath, 0o600);
     } catch (error) {
       await fsPromises.rm(tmp, { force: true }).catch(() => {});
-      console.warn('Failed to write settings file:', error);
+      console.warn(`Failed to write ${path.basename(filePath)}:`, error);
       throw error;
     }
   };
 
+  /**
+   * Persist a merged document: profile keys go to preferences.json (stamped
+   * when their value changed), everything else to settings.json. While
+   * preferences.json is unreadable its part is skipped rather than replaced.
+   */
+  const writeSettingsToDisk = async (settings, { surface = null, changedKeys = null } = {}) => {
+    const current = preferencesUnavailable ? { status: 'failed' } : await readPreferenceFields();
+    if (current.status === 'failed') {
+      // The profile part is not saved; settings.json keeps whatever legacy
+      // profile copy it already holds rather than losing it too.
+      preferencesUnavailable = true;
+      const onDisk = await readInstanceSettingsFromDisk();
+      await writeJsonFileAtomic(SETTINGS_FILE_PATH, JSON.stringify({
+        ...instancePartOf(settings),
+        ...profilePartOf(onDisk),
+      }, null, 2));
+      return;
+    }
+    const previousFields = current.status === 'ok' ? current.fields : {};
+    const nextFields = buildPreferencesFields(previousFields, settings, Date.now(), {
+      surface: normalizeSettingsSurface(surface),
+      changedKeys,
+    });
+    await writeJsonFileAtomic(SETTINGS_FILE_PATH, JSON.stringify(legacySettingsDocumentOf(settings, nextFields), null, 2));
+    await writePreferencesToDisk(nextFields);
+  };
+
   const validateProjectEntries = async (projects) => {
     if (!Array.isArray(projects)) {
       return [];
@@ -872,7 +981,7 @@ export const createSettingsRuntime = (deps) => {
 
   let hasCleanedOrphanedTempFiles = false;
 
-  const readSettingsFromDiskMigrated = async () => {
+  const readSettingsFromDiskMigrated = async ({ surface = null } = {}) => {
     if (!hasCleanedOrphanedTempFiles) {
       hasCleanedOrphanedTempFiles = true;
       await cleanupOrphanedSettingsTempFiles(path.dirname(SETTINGS_FILE_PATH));
@@ -889,16 +998,28 @@ export const createSettingsRuntime = (deps) => {
     if (migration1.changed || migration2.changed || migration3.changed || migration4.changed || migration5.changed || migration6.changed || migration7.changed || migration8.changed) {
       await writeSettingsToDisk(migration8.settings);
     }
-    return migration8.settings;
+    // Migrations run on the base view; a surface asks for its own resolution
+    // of the per-surface keys on top of the migrated files.
+    return normalizeSettingsSurface(surface) ? readSettingsFromDisk({ surface }) : migration8.settings;
   };
 
-  const persistSettings = async (changes) => {
+  const persistSettings = async (changes, { surface = null } = {}) => {
     persistSettingsLock = persistSettingsLock.then(async () => {
       // Log field names only — changes can carry credentials (UI password,
       // client tokens, tunnel tokens) that must never reach the log file.
       console.log('[persistSettings] Updating fields:', Object.keys(changes || {}).join(', ') || '(none)');
-      const current = await readSettingsFromDisk();
+      const current = await readSettingsFromDisk({ surface });
       const sanitized = sanitizeSettingsUpdate(changes);
+      for (const key of Object.keys(sanitized)) {
+        // Device state belongs to the install in front of the user, never to
+        // the instance; a client that still sends it is simply ignored.
+        if (isDeviceSettingsKey(key)) {
+          delete sanitized[key];
+        } else if (preferencesUnavailable && isProfileSettingsKey(key)) {
+          console.warn(`[persistSettings] Dropping ${key}: preferences file is unreadable`);
+          delete sanitized[key];
+        }
+      }
       let next = mergePersistedSettings(current, sanitized);
 
       const normalizedState = normalizeSettingsPaths(next);
@@ -962,7 +1083,7 @@ export const createSettingsRuntime = (deps) => {
         }
       }
 
-      await writeSettingsToDisk(next);
+      await writeSettingsToDisk(next, { surface, changedKeys: Object.keys(sanitized) });
       return formatSettingsResponse(next);
     });
 

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

@@ -6,7 +6,7 @@ import path from 'path';
 import { createProjectIdFromPath } 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,
@@ -68,8 +68,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 +80,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();
     }
@@ -248,3 +251,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,10 @@ 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 |
+| `<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 |
 
 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 +59,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 +94,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

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(