@aiworker/web 1.22.0 → 1.23.0

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

@@ -164,15 +164,22 @@ const sanitizePlanLinks = (value, now) => {
     const id = asNonEmptyString(entry.id);
     const file = asNonEmptyString(entry.file);
     if (!id || !file || !PLAN_FILE_PATTERN.test(file)) continue;
-    if (seenIds.has(id) || seenFiles.has(file)) continue;
+    // A personal file and a shared file may carry the same name: they live in different folders.
+    const shared = entry.shared === true;
+    const fileKey = `${shared ? 'shared' : 'personal'}/${file}`;
+    if (seenIds.has(id) || seenFiles.has(fileKey)) continue;
     seenIds.add(id);
-    seenFiles.add(file);
+    seenFiles.add(fileKey);
     result.push({
       id,
       file,
       title: sanitizePlanTitle(entry.title) || 'Plan',
       createdAt: Number.isFinite(entry.createdAt) && entry.createdAt >= 0 ? entry.createdAt : now,
       pinned: entry.pinned === true,
+      // The user's own plan that was moved into the team's folder: it keeps
+      // its id (session attachments still point at it) and this flag says
+      // which folder holds the file.
+      shared,
     });
   }
   return result.sort((a, b) => b.createdAt - a.createdAt);
@@ -185,8 +192,15 @@ const createEmptyContext = () => ({
   plans: [],
 });
 
+const SHARED_PLAN_ID_PREFIX = 'shared:';
+
 export const createProjectContextRuntime = (deps) => {
-  const { fsPromises, path, projectsDirPath, createId } = deps;
+  const { fsPromises, path, projectsDirPath, createId, resolveSharedPlansDir } = deps;
+  // The team's shared plans folder for a project (absolute path) or null; the
+  // project config runtime owns that answer (`plansDir` in the shared file).
+  const sharedPlansDirFor = typeof resolveSharedPlansDir === 'function'
+    ? resolveSharedPlansDir
+    : async () => null;
 
   const idFactory = typeof createId === 'function'
     ? createId
@@ -356,7 +370,7 @@ export const createProjectContextRuntime = (deps) => {
    * of identical content, so concurrent migrations converge instead of
    * interleaving.
    */
-  const readContext = async (projectId) => {
+  const readStoredContext = async (projectId) => {
     const now = Date.now();
     const stored = await readJson(contextPathFor(projectId));
 
@@ -385,6 +399,67 @@ export const createProjectContextRuntime = (deps) => {
     };
   };
 
+  /** The file name behind a shared plan id, or null when the id is not one. */
+  const sharedPlanFileOf = (planId) => {
+    if (typeof planId !== 'string' || !planId.startsWith(SHARED_PLAN_ID_PREFIX)) return null;
+    const file = planId.slice(SHARED_PLAN_ID_PREFIX.length);
+    return PLAN_FILE_PATTERN.test(file) ? file : null;
+  };
+
+  /**
+   * Plans in the team's shared folder: every `.md` file there, newest first,
+   * addressed by `shared:<file>`. Plans written by other tools have no
+   * manifest entry, so the title comes from the file each time.
+   */
+  const listSharedPlans = async (projectId, claimedFiles = new Set()) => {
+    const dir = await sharedPlansDirFor(projectId);
+    if (!dir) return { dir: null, plans: [] };
+    let entries;
+    try {
+      entries = await fsPromises.readdir(dir, { withFileTypes: true });
+    } catch (error) {
+      if (error && error.code === 'ENOENT') return { dir, plans: [] };
+      throw error;
+    }
+    const plans = [];
+    for (const entry of entries) {
+      if (!entry.isFile() || !PLAN_FILE_PATTERN.test(entry.name)) continue;
+      // Listed under its own id by the manifest entry that moved it there.
+      if (claimedFiles.has(entry.name)) continue;
+      const filePath = path.join(dir, entry.name);
+      const [raw, stat] = await Promise.all([fsPromises.readFile(filePath, 'utf8'), fsPromises.stat(filePath)]);
+      plans.push({
+        id: `${SHARED_PLAN_ID_PREFIX}${entry.name}`,
+        file: entry.name,
+        title: parsePlanMarkdown(raw).title,
+        createdAt: Math.round(stat.mtimeMs),
+        pinned: false,
+        source: 'shared',
+      });
+    }
+    plans.sort((left, right) => right.createdAt - left.createdAt);
+    return { dir, plans };
+  };
+
+  /** What clients see: the stored context plus the team's shared plans, each marked with its source. */
+  const readContext = async (projectId) => {
+    const stored = await readStoredContext(projectId);
+    const claimed = new Set(stored.plans.filter((plan) => plan.shared).map((plan) => plan.file));
+    const shared = await listSharedPlans(projectId, claimed);
+    const own = stored.plans
+      // A moved plan is only reachable while the project still has a shared folder.
+      .filter((plan) => !plan.shared || shared.dir)
+      .map(({ shared: isShared, ...plan }) => ({ ...plan, source: isShared ? 'shared' : 'personal' }));
+    return {
+      ...stored,
+      plans: [...own, ...shared.plans],
+      sharedPlansDir: shared.dir,
+    };
+  };
+
+  /** The folder a manifest plan's file lives in; null for a moved plan when the project lost its shared folder. */
+  const folderOfLink = async (projectId, link) => (link.shared ? sharedPlansDirFor(projectId) : plansDirFor(projectId));
+
   const writeContext = async (projectId, context) => {
     await writeJsonAtomic(contextPathFor(projectId), {
       version: PROJECT_CONTEXT_VERSION,
@@ -397,7 +472,7 @@ export const createProjectContextRuntime = (deps) => {
   const saveTodos = async (projectId, todos) => {
     return withWriteLock(projectId, async () => {
       const now = Date.now();
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const next = { ...current, todos: sanitizeTodos(todos, now) };
       await writeContext(projectId, next);
       return next;
@@ -420,7 +495,7 @@ export const createProjectContextRuntime = (deps) => {
 
     return withWriteLock(projectId, async () => {
       const now = Date.now();
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       if (current.notes.length >= PROJECT_NOTE_MAX_ITEMS) {
         throw new Error(`A project can hold at most ${PROJECT_NOTE_MAX_ITEMS} notes`);
       }
@@ -462,7 +537,7 @@ export const createProjectContextRuntime = (deps) => {
 
     return withWriteLock(projectId, async () => {
       const now = Date.now();
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const existing = current.notes.find((note) => note.id === id);
       if (!existing) {
         return null;
@@ -486,7 +561,7 @@ export const createProjectContextRuntime = (deps) => {
     }
 
     return withWriteLock(projectId, async () => {
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       if (!current.notes.some((note) => note.id === id)) {
         return { deleted: false, context: current };
       }
@@ -501,22 +576,38 @@ export const createProjectContextRuntime = (deps) => {
     if (!id) {
       throw new Error('planId is required');
     }
-    const context = await readContext(projectId);
+    const sharedFile = sharedPlanFileOf(id);
+    if (sharedFile) {
+      const dir = await sharedPlansDirFor(projectId);
+      if (!dir) return null;
+      let raw;
+      try {
+        raw = await fsPromises.readFile(path.join(dir, sharedFile), 'utf8');
+      } catch (error) {
+        if (error && error.code === 'ENOENT') return null;
+        throw error;
+      }
+      const parsed = parsePlanMarkdown(raw);
+      return { id, file: sharedFile, createdAt: 0, title: parsed.title, body: parsed.body, raw, source: 'shared' };
+    }
+    const context = await readStoredContext(projectId);
     const link = context.plans.find((entry) => entry.id === id);
     if (!link) {
       return null;
     }
 
+    const folder = await folderOfLink(projectId, link);
+    if (!folder) return null;
     let raw;
     try {
-      raw = await fsPromises.readFile(path.join(plansDirFor(projectId), link.file), 'utf8');
+      raw = await fsPromises.readFile(path.join(folder, link.file), 'utf8');
     } catch (error) {
       if (error && error.code === 'ENOENT') return null;
       throw error;
     }
 
     const parsed = parsePlanMarkdown(raw);
-    return { id: link.id, file: link.file, createdAt: link.createdAt, title: parsed.title, body: parsed.body, raw };
+    return { id: link.id, file: link.file, createdAt: link.createdAt, title: parsed.title, body: parsed.body, raw, source: link.shared ? 'shared' : 'personal' };
   };
 
   /**
@@ -541,14 +632,37 @@ export const createProjectContextRuntime = (deps) => {
     }
     const raw = clampLength(value.raw, PROJECT_PLAN_BODY_MAX_LENGTH);
 
+    const sharedFile = sharedPlanFileOf(id);
+    if (sharedFile) {
+      // A shared plan is the file itself: written verbatim, no manifest.
+      return withWriteLock(projectId, async () => {
+        const dir = await sharedPlansDirFor(projectId);
+        if (!dir) return null;
+        const filePath = path.join(dir, sharedFile);
+        try {
+          await fsPromises.access(filePath);
+        } catch (error) {
+          if (error && error.code === 'ENOENT') return null;
+          throw error;
+        }
+        await fsPromises.writeFile(filePath, raw, 'utf8');
+        const parsed = parsePlanMarkdown(raw);
+        const context = await readContext(projectId);
+        const plan = context.plans.find((entry) => entry.id === id) ?? { id, file: sharedFile, title: parsed.title, createdAt: Date.now(), pinned: false, source: 'shared' };
+        return { plan, context, title: parsed.title, body: parsed.body, raw };
+      });
+    }
+
     return withWriteLock(projectId, async () => {
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const link = current.plans.find((entry) => entry.id === id);
       if (!link) {
         return null;
       }
 
-      const filePath = path.join(plansDirFor(projectId), link.file);
+      const folder = await folderOfLink(projectId, link);
+      if (!folder) return null;
+      const filePath = path.join(folder, link.file);
       // Refuse to recreate a file that was deleted underneath us: the link is
       // already dead, and writing here would resurrect it with editor content
       // the user believed was discarded.
@@ -569,7 +683,8 @@ export const createProjectContextRuntime = (deps) => {
       };
       await writeContext(projectId, next);
 
-      return { plan: nextLink, context: next, title: parsed.title, body: parsed.body, raw };
+      const { shared: isShared, ...publicLink } = nextLink;
+      return { plan: { ...publicLink, source: isShared ? 'shared' : 'personal' }, context: await readContext(projectId), title: parsed.title, body: parsed.body, raw };
     });
   };
 
@@ -586,7 +701,7 @@ export const createProjectContextRuntime = (deps) => {
     const body = clampLength(typeof value?.body === 'string' ? value.body : '', PROJECT_PLAN_BODY_MAX_LENGTH);
 
     return withWriteLock(projectId, async () => {
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const createdAt = Date.now();
       const plansDir = plansDirFor(projectId);
       await fsPromises.mkdir(plansDir, { recursive: true });
@@ -594,7 +709,7 @@ export const createProjectContextRuntime = (deps) => {
       const baseName = `${createdAt}-${slugifyPlanTitle(title)}`;
       let file = `${baseName}.md`;
       let attempt = 1;
-      while (current.plans.some((entry) => entry.file === file)) {
+      while (current.plans.some((entry) => !entry.shared && entry.file === file)) {
         file = `${baseName}-${attempt}.md`;
         attempt += 1;
       }
@@ -604,7 +719,7 @@ export const createProjectContextRuntime = (deps) => {
       const link = { id: idFactory(), file, title, createdAt, pinned: false };
       const next = { ...current, plans: [link, ...current.plans] };
       await writeContext(projectId, next);
-      return { plan: link, context: next };
+      return { plan: { ...link, source: 'personal' }, context: await readContext(projectId) };
     });
   };
 
@@ -623,7 +738,7 @@ export const createProjectContextRuntime = (deps) => {
     }
 
     return withWriteLock(projectId, async () => {
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const existing = current.plans.find((entry) => entry.id === id);
       if (!existing) {
         return null;
@@ -631,7 +746,8 @@ export const createProjectContextRuntime = (deps) => {
       const plan = { ...existing, pinned: pinned === true };
       const next = { ...current, plans: current.plans.map((entry) => (entry.id === id ? plan : entry)) };
       await writeContext(projectId, next);
-      return { plan, context: next };
+      const { shared: isShared, ...publicPlan } = plan;
+      return { plan: { ...publicPlan, source: isShared ? 'shared' : 'personal' }, context: await readContext(projectId) };
     });
   };
 
@@ -641,17 +757,124 @@ export const createProjectContextRuntime = (deps) => {
       throw new Error('planId is required');
     }
 
+    const sharedFile = sharedPlanFileOf(id);
+    if (sharedFile) {
+      return withWriteLock(projectId, async () => {
+        const dir = await sharedPlansDirFor(projectId);
+        const filePath = dir ? path.join(dir, sharedFile) : null;
+        const exists = filePath ? await fsPromises.access(filePath).then(() => true, () => false) : false;
+        if (!exists) return { deleted: false, context: await readContext(projectId) };
+        await fsPromises.rm(filePath, { force: true });
+        return { deleted: true, context: await readContext(projectId) };
+      });
+    }
+
     return withWriteLock(projectId, async () => {
-      const current = await readContext(projectId);
+      const current = await readStoredContext(projectId);
       const link = current.plans.find((entry) => entry.id === id);
       if (!link) {
-        return { deleted: false, context: current };
+        return { deleted: false, context: await readContext(projectId) };
       }
 
       const next = { ...current, plans: current.plans.filter((entry) => entry.id !== id) };
       await writeContext(projectId, next);
-      await fsPromises.rm(path.join(plansDirFor(projectId), link.file), { force: true });
-      return { deleted: true, context: next };
+      const folder = await folderOfLink(projectId, link);
+      if (folder) await fsPromises.rm(path.join(folder, link.file), { force: true });
+      return { deleted: true, context: await readContext(projectId) };
+    });
+  };
+
+  /** A free file name in `dir`, keeping the wanted base name unless it is taken. */
+  const freeFileNameIn = async (dir, wanted, taken = new Set()) => {
+    const base = wanted.replace(/\.md$/, '');
+    let file = wanted;
+    let attempt = 1;
+    while (taken.has(file) || await fsPromises.access(path.join(dir, file)).then(() => true, () => false)) {
+      file = `${base}-${attempt}.md`;
+      attempt += 1;
+    }
+    return file;
+  };
+
+  const moveFile = async (from, to) => {
+    try {
+      await fsPromises.rename(from, to);
+    } catch (error) {
+      if (!error || error.code !== 'EXDEV') throw error;
+      await fsPromises.copyFile(from, to);
+      await fsPromises.rm(from, { force: true });
+    }
+  };
+
+  /**
+   * Move one of the user's plans into the team's shared folder. The plan
+   * keeps its id: the manifest entry stays and gets the `shared` flag, so a
+   * session that attached the plan still finds it. The markdown moves first,
+   * then the manifest is written; a failure in between leaves the file in the
+   * shared folder (listed there as `shared:<file>`) and a dead personal entry
+   * that `readPlan` reports as gone. Needs a shared plans folder; refused
+   * (validation error) when the project has none.
+   */
+  const sharePlan = async (projectId, planId) => {
+    const id = asNonEmptyString(planId);
+    if (!id) throw new Error('planId is required');
+    return withWriteLock(projectId, async () => {
+      const dir = await sharedPlansDirFor(projectId);
+      if (!dir) throw new Error('shared plans folder is required');
+      const current = await readStoredContext(projectId);
+      const link = current.plans.find((entry) => entry.id === id);
+      if (!link || link.shared) return null;
+      const from = path.join(plansDirFor(projectId), link.file);
+      const exists = await fsPromises.access(from).then(() => true, () => false);
+      if (!exists) return null;
+      await fsPromises.mkdir(dir, { recursive: true });
+      const file = await freeFileNameIn(dir, link.file);
+      await moveFile(from, path.join(dir, file));
+      const moved = { ...link, file, shared: true };
+      await writeContext(projectId, { ...current, plans: current.plans.map((entry) => (entry.id === id ? moved : entry)) });
+      const context = await readContext(projectId);
+      return { plan: context.plans.find((entry) => entry.id === id), context };
+    });
+  };
+
+  /**
+   * Move a shared plan back into the user's own plans; the reverse of
+   * `sharePlan`. A plan the user moved keeps its id; a plan that only ever
+   * lived in the team's folder (`shared:<file>`) gets a manifest entry now.
+   */
+  const unsharePlan = async (projectId, planId) => {
+    const id = asNonEmptyString(planId);
+    if (!id) throw new Error('planId is required');
+    return withWriteLock(projectId, async () => {
+      const dir = await sharedPlansDirFor(projectId);
+      if (!dir) return null;
+      const current = await readStoredContext(projectId);
+      const ownLink = current.plans.find((entry) => entry.id === id && entry.shared);
+      const sharedFile = ownLink ? ownLink.file : sharedPlanFileOf(id);
+      if (!sharedFile) return null;
+      const from = path.join(dir, sharedFile);
+      let raw;
+      try {
+        raw = await fsPromises.readFile(from, 'utf8');
+      } catch (error) {
+        if (error && error.code === 'ENOENT') return null;
+        throw error;
+      }
+      const plansDir = plansDirFor(projectId);
+      await fsPromises.mkdir(plansDir, { recursive: true });
+      const taken = new Set(current.plans.filter((entry) => !entry.shared).map((entry) => entry.file));
+      const file = await freeFileNameIn(plansDir, sharedFile, taken);
+      await moveFile(from, path.join(plansDir, file));
+      const title = parsePlanMarkdown(raw).title;
+      const link = ownLink
+        ? { ...ownLink, file, title, shared: false }
+        : { id: idFactory(), file, title, createdAt: Date.now(), pinned: false, shared: false };
+      const plans = ownLink
+        ? current.plans.map((entry) => (entry.id === id ? link : entry))
+        : [link, ...current.plans];
+      await writeContext(projectId, { ...current, plans });
+      const { shared: _movedFlag, ...publicLink } = link;
+      return { plan: { ...publicLink, source: 'personal' }, context: await readContext(projectId) };
     });
   };
 
@@ -666,6 +889,8 @@ export const createProjectContextRuntime = (deps) => {
     createPlan,
     setPlanPinned,
     deletePlan,
+    sharePlan,
+    unsharePlan,
     contextPathFor,
     plansDirFor,
   };

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

@@ -52,6 +52,7 @@ describe('readContext', () => {
       notes: [],
       todos: [],
       plans: [],
+      sharedPlansDir: null,
     });
   });
 
@@ -134,7 +135,7 @@ describe('legacy migration', () => {
     const context = await runtime.readContext(PROJECT_ID);
     expect(context.notes.map((note) => note.body)).toEqual(['legacy notes']);
     expect(context.todos).toEqual([{ id: 't1', text: 'legacy todo', completed: true, createdAt: 5 }]);
-    expect(context.plans).toEqual([{ id: 'p1', file: '10-old.md', title: 'Old plan', createdAt: 10, pinned: false }]);
+    expect(context.plans).toEqual([{ id: 'p1', file: '10-old.md', title: 'Old plan', createdAt: 10, pinned: false, source: 'personal' }]);
 
     const remaining = await readJson(legacyConfigPath());
     expect(remaining).toEqual({
@@ -152,7 +153,7 @@ describe('legacy migration', () => {
     });
 
     const context = await runtime.readContext(PROJECT_ID);
-    expect(context.plans).toEqual([{ id: 'p1', file: 'stray.md', title: 'Stray', createdAt: 10, pinned: false }]);
+    expect(context.plans).toEqual([{ id: 'p1', file: 'stray.md', title: 'Stray', createdAt: 10, pinned: false, source: 'personal' }]);
     expect(await fsPromises.readFile(path.join(plansDir(), 'stray.md'), 'utf8')).toContain('recovered');
   });
 
@@ -170,7 +171,7 @@ describe('legacy migration', () => {
   test('does not run when the legacy config holds no context keys', async () => {
     await writeJson(legacyConfigPath(), { 'setup-worktree': ['bun install'] });
 
-    expect(await runtime.readContext(PROJECT_ID)).toEqual({ version: 2, notes: [], todos: [], plans: [] });
+    expect(await runtime.readContext(PROJECT_ID)).toEqual({ version: 2, notes: [], todos: [], plans: [], sharedPlansDir: null });
     await expect(fsPromises.access(contextPath())).rejects.toThrow();
     expect(await readJson(legacyConfigPath())).toEqual({ 'setup-worktree': ['bun install'] });
   });
@@ -479,6 +480,108 @@ describe('plans', () => {
   });
 });
 
+describe('shared plans', () => {
+  let sharedDir;
+  let sharedRuntime;
+
+  beforeEach(async () => {
+    sharedDir = path.join(projectsDirPath, 'repo', 'docs', 'plans');
+    sharedRuntime = createProjectContextRuntime({
+      fsPromises,
+      path,
+      projectsDirPath,
+      createId: () => `plan-${++idCounter}`,
+      resolveSharedPlansDir: async () => sharedDir,
+    });
+  });
+
+  test('lists the shared folder\'s markdown files after the personal plans, marked shared, and reads them by file', async () => {
+    await fsPromises.mkdir(sharedDir, { recursive: true });
+    await fsPromises.writeFile(path.join(sharedDir, 'roadmap.md'), '# Roadmap\n\n- ship it\n');
+    await fsPromises.writeFile(path.join(sharedDir, 'notes.txt'), 'not a plan');
+    await fsPromises.writeFile(path.join(sharedDir, 'untitled.md'), 'first line only');
+    const mine = await sharedRuntime.createPlan(PROJECT_ID, { title: 'Mine', body: 'x' });
+
+    const context = await sharedRuntime.readContext(PROJECT_ID);
+    expect(context.sharedPlansDir).toBe(sharedDir);
+    expect(context.plans.map((plan) => `${plan.id}:${plan.source}`)).toEqual(expect.arrayContaining([
+      `${mine.plan.id}:personal`, 'shared:roadmap.md:shared', 'shared:untitled.md:shared',
+    ]));
+    expect(context.plans[0].id).toBe(mine.plan.id);
+    expect(context.plans.find((plan) => plan.id === 'shared:untitled.md').title).toBe('first line only');
+
+    const read = await sharedRuntime.readPlan(PROJECT_ID, 'shared:roadmap.md');
+    expect(read.title).toBe('Roadmap');
+    expect(read.raw).toBe('# Roadmap\n\n- ship it\n');
+    expect(await sharedRuntime.readPlan(PROJECT_ID, 'shared:missing.md')).toBeNull();
+    expect(await sharedRuntime.readPlan(PROJECT_ID, 'shared:../escape.md')).toBeNull();
+  });
+
+  test('a missing shared folder lists nothing; no folder configured lists nothing', async () => {
+    expect((await sharedRuntime.readContext(PROJECT_ID)).plans).toEqual([]);
+    expect((await runtime.readContext(PROJECT_ID)).sharedPlansDir).toBeNull();
+  });
+
+  test('updates and deletes a shared plan in place, verbatim', async () => {
+    await fsPromises.mkdir(sharedDir, { recursive: true });
+    await fsPromises.writeFile(path.join(sharedDir, 'a.md'), '# A\n');
+    const updated = await sharedRuntime.updatePlan(PROJECT_ID, 'shared:a.md', { raw: '# Renamed\n\nbody\n' });
+    expect(updated.plan.title).toBe('Renamed');
+    expect(updated.plan.source).toBe('shared');
+    expect(await fsPromises.readFile(path.join(sharedDir, 'a.md'), 'utf8')).toBe('# Renamed\n\nbody\n');
+    expect(await sharedRuntime.updatePlan(PROJECT_ID, 'shared:gone.md', { raw: 'x' })).toBeNull();
+    expect(await sharedRuntime.setPlanPinned(PROJECT_ID, 'shared:a.md', true)).toBeNull();
+
+    const deleted = await sharedRuntime.deletePlan(PROJECT_ID, 'shared:a.md');
+    expect(deleted.deleted).toBe(true);
+    await expect(fsPromises.access(path.join(sharedDir, 'a.md'))).rejects.toThrow();
+    expect((await sharedRuntime.deletePlan(PROJECT_ID, 'shared:a.md')).deleted).toBe(false);
+  });
+
+  test('share moves a personal plan into the shared folder and unshare brings it back, avoiding name collisions', async () => {
+    const { plan } = await sharedRuntime.createPlan(PROJECT_ID, { title: 'Mine', body: 'body' });
+    const shared = await sharedRuntime.sharePlan(PROJECT_ID, plan.id);
+    // The id survives the move: a session that attached the plan still finds it.
+    expect(shared.plan.id).toBe(plan.id);
+    expect(shared.plan.source).toBe('shared');
+    expect(shared.context.plans.map((entry) => `${entry.id}:${entry.source}`)).toEqual([`${plan.id}:shared`]);
+    await expect(fsPromises.access(path.join(plansDir(), plan.file))).rejects.toThrow();
+    expect(await fsPromises.readFile(path.join(sharedDir, plan.file), 'utf8')).toBe('# Mine\n\nbody');
+    expect((await readJson(path.join(projectsDirPath, PROJECT_ID, 'context.json'))).plans[0]).toMatchObject({ id: plan.id, shared: true });
+    const readMoved = await sharedRuntime.readPlan(PROJECT_ID, plan.id);
+    expect(readMoved.source).toBe('shared');
+    expect(readMoved.raw).toBe('# Mine\n\nbody');
+    expect((await sharedRuntime.updatePlan(PROJECT_ID, plan.id, { raw: '# Mine v2\n' })).plan).toMatchObject({ id: plan.id, title: 'Mine v2', source: 'shared' });
+    expect(await fsPromises.readFile(path.join(sharedDir, plan.file), 'utf8')).toBe('# Mine v2\n');
+
+    // A personal file with the same name already exists: the returning plan gets a suffix, same id.
+    await fsPromises.mkdir(plansDir(), { recursive: true });
+    await fsPromises.writeFile(path.join(plansDir(), plan.file), 'squatter');
+    const back = await sharedRuntime.unsharePlan(PROJECT_ID, plan.id);
+    expect(back.plan.id).toBe(plan.id);
+    expect(back.plan.source).toBe('personal');
+    expect(back.plan.file).toBe(plan.file.replace(/\.md$/, '-1.md'));
+    expect(back.plan.title).toBe('Mine v2');
+    expect(back.context.plans.map((entry) => `${entry.id}:${entry.source}`)).toEqual([`${plan.id}:personal`]);
+    await expect(fsPromises.access(path.join(sharedDir, plan.file))).rejects.toThrow();
+    expect(await sharedRuntime.unsharePlan(PROJECT_ID, plan.id)).toBeNull();
+    expect(await sharedRuntime.sharePlan(PROJECT_ID, 'nope')).toBeNull();
+
+    // A plan that only ever lived in the team's folder gets an id of its own on the way in.
+    await fsPromises.writeFile(path.join(sharedDir, 'foreign.md'), '# Foreign\n');
+    const adopted = await sharedRuntime.unsharePlan(PROJECT_ID, 'shared:foreign.md');
+    expect(adopted.plan.id).not.toMatch(/^shared:/);
+    expect(adopted.plan.title).toBe('Foreign');
+    expect(adopted.plan.source).toBe('personal');
+  });
+
+  test('share is refused without a shared plans folder', async () => {
+    const { plan } = await runtime.createPlan(PROJECT_ID, { title: 'Mine', body: 'x' });
+    await expect(runtime.sharePlan(PROJECT_ID, plan.id)).rejects.toThrow('shared plans folder is required');
+    expect((await runtime.readContext(PROJECT_ID)).plans.map((entry) => entry.id)).toEqual([plan.id]);
+  });
+});
+
 describe('parsePlanMarkdown', () => {
   test('reads the leading heading as the title', () => {
     expect(parsePlanMarkdown('# Title\n\nbody')).toEqual({ title: 'Title', body: 'body' });

package/server/lib/projects/DOCUMENTATION.md

@@ -0,0 +1,76 @@
+# 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.
+- `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 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.