@aiworker/web 1.22.0 → 1.23.0

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

@@ -1,6 +1,21 @@
 import { DateTime, IANAZone } from 'luxon';
 import parser from 'cron-parser';
 
+import { projectPathFromId } from './project-id.js';
+import {
+  DEFAULT_PLANS_DIR,
+  EMPTY_SHARED_PROJECT_CONFIG,
+  SHARED_CONFIG_RELATIVE_PATH,
+  applySharedProjectSetupPatch,
+  isSharedProjectConfigEmpty,
+  mergeProjectSetup,
+  parseSharedProjectConfig,
+  projectSetupPatchToStored,
+  projectSetupViewOf,
+  serializeSharedProjectConfig,
+  sharedTrustHashOf,
+} from './project-setup.js';
+
 const PROJECT_CONFIG_VERSION = 1;
 export const MAX_TASK_NAME_LENGTH = 80;
 const MAX_TASK_PROMPT_LENGTH = 20_000;
@@ -255,7 +270,7 @@ const normalizeState = (value, fallback) => {
     ? Math.max(0, Math.round(source.nextRunAt))
     : undefined;
   // Absolute ms of the schedule occurrence last claimed for dispatch. Used so
-  // two OpenChamber server instances sharing this config cannot both start a
+  // two AiWorker server instances sharing this config cannot both start a
   // run for the same daily/weekly/cron/once slot (see issue #2710).
   const lastScheduledFor = typeof source.lastScheduledFor === 'number' && Number.isFinite(source.lastScheduledFor)
     ? Math.max(0, Math.round(source.lastScheduledFor))
@@ -548,21 +563,16 @@ export const createProjectConfigRuntime = (deps) => {
     })
   );
 
-  const writeProjectConfigToDisk = async (projectID, config) => {
+  // Atomic whole-document write; callers hand in the merged document so the
+  // keys they do not own survive untouched.
+  const writeRawProjectConfigToDisk = async (projectID, document) => {
     const filePath = resolveProjectConfigPath(projectID);
     const parentDirectory = path.dirname(filePath);
     const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 
-    const existing = await readRawProjectConfigFromDisk(projectID);
-    const merged = {
-      ...existing,
-      version: PROJECT_CONFIG_VERSION,
-      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
-    };
-
     await fsPromises.mkdir(parentDirectory, { recursive: true });
     try {
-      await fsPromises.writeFile(temporaryPath, JSON.stringify(merged, null, 2), 'utf8');
+      await fsPromises.writeFile(temporaryPath, JSON.stringify(document, null, 2), 'utf8');
       await fsPromises.rename(temporaryPath, filePath);
     } catch (error) {
       await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
@@ -570,6 +580,15 @@ export const createProjectConfigRuntime = (deps) => {
     }
   };
 
+  const writeProjectConfigToDisk = async (projectID, config) => {
+    const existing = await readRawProjectConfigFromDisk(projectID);
+    await writeRawProjectConfigToDisk(projectID, {
+      ...existing,
+      version: PROJECT_CONFIG_VERSION,
+      scheduledTasks: Array.isArray(config?.scheduledTasks) ? config.scheduledTasks : [],
+    });
+  };
+
   const withProjectWriteLock = async (projectID, mutate) => {
     const key = sanitizeProjectID(projectID);
     const previous = writeLocks.get(key) || Promise.resolve();
@@ -717,7 +736,7 @@ export const createProjectConfigRuntime = (deps) => {
    * `predicate(currentTask)` is evaluated after the latest on-disk read; when
    * it returns false the write is skipped and `{ updated: false }` is returned.
    * Used by the scheduled-tasks runtime to claim a single schedule occurrence
-   * across concurrent OpenChamber server instances.
+   * across concurrent AiWorker server instances.
    */
   const updateScheduledTaskStateIf = async (projectID, taskID, predicate, statePatch) => {
     return withProjectWriteLock(projectID, async () => {
@@ -905,7 +924,121 @@ export const createProjectConfigRuntime = (deps) => {
     });
   };
 
+  // The client-owned part of the file (worktree setup, project actions, draft
+  // starters); see `project-setup.js`. Reads are lock-free like task lists;
+  // an update merges the sanitized patch over the raw document under the same
+  // cross-process lock the task writers use, so neither side clobbers the other.
+  // The shared file lives in the project's checkout. The checkout path comes
+  // from the id itself (`path_<base64url>`), with the personal file's
+  // `projectPath` as the fallback for ids of another form. A missing file is
+  // the normal case; an unreadable or unparsable one is reported as invalid,
+  // never as "no shared setup".
+  const projectPathOf = (projectID, personalRaw) => (
+    projectPathFromId(projectID) || (typeof personalRaw.projectPath === 'string' ? personalRaw.projectPath.trim() : '')
+  );
+  const sharedConfigPathOf = (projectPath) => path.join(projectPath, ...SHARED_CONFIG_RELATIVE_PATH.split('/'));
+
+  const readSharedProjectConfig = async (projectID, personalRaw) => {
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return { status: 'missing' };
+    let raw;
+    try {
+      raw = await fsPromises.readFile(sharedConfigPathOf(projectPath), 'utf8');
+    } catch (error) {
+      if (error && typeof error === 'object' && error.code === 'ENOENT') return { status: 'missing' };
+      return { status: 'invalid', reason: error instanceof Error ? error.message : String(error) };
+    }
+    return parseSharedProjectConfig(raw);
+  };
+
+  const mergedProjectSetupOf = async (projectID, personalRaw) => (
+    mergeProjectSetup(projectSetupViewOf(personalRaw), await readSharedProjectConfig(projectID, personalRaw))
+  );
+
+  const readProjectSetup = async (projectID) => mergedProjectSetupOf(projectID, await readRawProjectConfigFromDisk(projectID));
+
+  const updateProjectSetup = async (projectID, patch) => {
+    const stored = projectSetupPatchToStored(patch);
+    return withProjectWriteLock(projectID, async () => {
+      const existing = await readRawProjectConfigFromDisk(projectID);
+      const merged = { ...existing, ...stored };
+      for (const [key, value] of Object.entries(stored)) {
+        if (value === undefined) delete merged[key];
+      }
+      await writeRawProjectConfigToDisk(projectID, merged);
+      return mergedProjectSetupOf(projectID, merged);
+    });
+  };
+
+  /**
+   * Change the team's shared file in the checkout: the patch replaces the
+   * keys it names over the current file (a broken file counts as empty, so
+   * a write repairs it). A result with nothing in it removes the file (and
+   * the `.aiworker` folder when that leaves it empty), so unsharing the
+   * last item leaves no trace. The writer has seen the commands it just
+   * shared, so the personal trust record is set to the new hash on this
+   * instance; teammates still get the prompt.
+   */
+  const updateSharedProjectSetup = async (projectID, patch) => (
+    withProjectWriteLock(projectID, async () => {
+      const personalRaw = await readRawProjectConfigFromDisk(projectID);
+      const projectPath = projectPathOf(projectID, personalRaw);
+      if (!projectPath) throw new Error('project checkout not found');
+      try {
+        if (!(await fsPromises.stat(projectPath)).isDirectory()) throw new Error('project checkout not found');
+      } catch {
+        throw new Error('project checkout not found');
+      }
+      const currentRead = await readSharedProjectConfig(projectID, personalRaw);
+      const current = currentRead.status === 'ok' ? currentRead.config : EMPTY_SHARED_PROJECT_CONFIG;
+      const next = applySharedProjectSetupPatch(current, patch);
+
+      const filePath = sharedConfigPathOf(projectPath);
+      if (isSharedProjectConfigEmpty(next)) {
+        await fsPromises.rm(filePath, { force: true });
+        await fsPromises.rmdir(path.dirname(filePath)).catch(() => {});
+      } else {
+        await fsPromises.mkdir(path.dirname(filePath), { recursive: true });
+        const temporaryPath = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+        try {
+          await fsPromises.writeFile(temporaryPath, serializeSharedProjectConfig(next), 'utf8');
+          await fsPromises.rename(temporaryPath, filePath);
+        } catch (error) {
+          await fsPromises.rm(temporaryPath, { force: true }).catch(() => {});
+          throw error;
+        }
+      }
+
+      const hash = sharedTrustHashOf(next);
+      const personalNext = { ...personalRaw };
+      if (hash) personalNext.sharedTrust = { hash, trustedAt: Date.now() };
+      else delete personalNext.sharedTrust;
+      await writeRawProjectConfigToDisk(projectID, personalNext);
+      return mergedProjectSetupOf(projectID, personalNext);
+    })
+  );
+
+  /**
+   * The absolute repository plans folder of a project: `plansDir` from the
+   * shared file when set, else the default `.aiworker/plans`. Setting
+   * `plansDir` replaces the default outright (nothing is read from it any
+   * more); moving files between the two is the user's job. Null only when the
+   * checkout cannot be located.
+   */
+  const resolveSharedPlansDir = async (projectID) => {
+    const personalRaw = await readRawProjectConfigFromDisk(projectID);
+    const projectPath = projectPathOf(projectID, personalRaw);
+    if (!projectPath) return null;
+    const shared = await readSharedProjectConfig(projectID, personalRaw);
+    const relative = shared.status === 'ok' && shared.config.plansDir ? shared.config.plansDir : DEFAULT_PLANS_DIR;
+    return path.join(projectPath, ...relative.split('/'));
+  };
+
   return {
+    readProjectSetup,
+    updateProjectSetup,
+    updateSharedProjectSetup,
+    resolveSharedPlansDir,
     listScheduledTasks,
     upsertScheduledTask,
     deleteScheduledTask,

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

@@ -11,3 +11,20 @@ export const createProjectIdFromPath = (projectPath) => {
 
   return `path_${Buffer.from(normalized, 'utf8').toString('base64url')}`;
 };
+
+/**
+ * The path a `path_<base64url>` id was made from, or `''` when the id is not
+ * of that form. The projects dir names files by this id, so the server can
+ * find the project's checkout (and the shared config inside it) from the id
+ * alone.
+ */
+export const projectPathFromId = (projectId) => {
+  if (typeof projectId !== 'string' || !projectId.startsWith('path_')) return '';
+  const encoded = projectId.slice('path_'.length);
+  if (!encoded || !/^[A-Za-z0-9_-]+$/.test(encoded)) return '';
+  try {
+    return Buffer.from(encoded, 'base64url').toString('utf8');
+  } catch {
+    return '';
+  }
+};

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

@@ -0,0 +1,409 @@
+// A project's setup — worktree setup commands, project actions, pinned draft
+// starters — comes from two files:
+//
+// - the personal file `~/.config/openchamber/projects/<projectId>.json`
+//   (client-owned keys; server-owned `version` / `scheduledTasks` live beside
+//   them and are never touched here), and
+// - the shared file `<repo>/.aiworker/project.json`, committed by a team so
+//   a teammate who pulls the code gets the setup without configuring anything.
+//
+// This module knows both shapes and the one merge rule per field. The route
+// and the VS Code bridge (`packages/vscode/src/project-setup.ts`, a mirror of
+// this file) use the same code paths so a value reads back the same on every
+// surface.
+
+import crypto from 'node:crypto';
+
+const ACTION_NAME_MAX_LENGTH = 80;
+const ACTION_COMMAND_MAX_LENGTH = 4000;
+const ACTION_OPEN_URL_MAX_LENGTH = 2000;
+const ACTION_DESKTOP_FORWARD_MAX_LENGTH = 300;
+const SETUP_COMMAND_MAX_LENGTH = 4000;
+const SETUP_COMMANDS_MAX = 50;
+
+const ACTION_PLATFORMS = new Set(['macos', 'linux', 'windows']);
+const SETUP_WORKTREE_MODES = new Set(['append', 'replace']);
+
+const isObjectRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const clamp = (value, maxLength) => (value.length > maxLength ? value.slice(0, maxLength) : value);
+
+const trimmedString = (value) => (typeof value === 'string' ? value.trim() : '');
+
+/** Setup commands: non-empty trimmed strings, capped in count and length. */
+export const sanitizeSetupCommands = (value) => {
+  if (!Array.isArray(value)) return [];
+  const commands = [];
+  for (const entry of value) {
+    const command = clamp(trimmedString(entry), SETUP_COMMAND_MAX_LENGTH);
+    if (!command) continue;
+    commands.push(command);
+    if (commands.length >= SETUP_COMMANDS_MAX) break;
+  }
+  return commands;
+};
+
+const sanitizeActionPlatforms = (value) => {
+  if (!Array.isArray(value)) return [];
+  const platforms = [];
+  for (const entry of value) {
+    const platform = trimmedString(entry).toLowerCase();
+    if (ACTION_PLATFORMS.has(platform) && !platforms.includes(platform)) platforms.push(platform);
+  }
+  return platforms;
+};
+
+/**
+ * Project actions: `id`, `name`, and `command` are required and ids are
+ * unique; every optional field is dropped when empty so the stored record
+ * carries only what the user set. `runIn` keeps only the one value the UI
+ * understands (`parent`); anything else means "run in the worktree".
+ */
+export const sanitizeProjectActions = (value) => {
+  if (!Array.isArray(value)) return [];
+  const actions = [];
+  const seenIds = new Set();
+  for (const entry of value) {
+    if (!isObjectRecord(entry)) continue;
+    const id = trimmedString(entry.id);
+    const name = clamp(trimmedString(entry.name), ACTION_NAME_MAX_LENGTH);
+    const command = clamp(trimmedString(entry.command), ACTION_COMMAND_MAX_LENGTH);
+    if (!id || !name || !command || seenIds.has(id)) continue;
+    seenIds.add(id);
+
+    const icon = trimmedString(entry.icon);
+    const platforms = sanitizeActionPlatforms(entry.platforms);
+    const openUrl = clamp(trimmedString(entry.openUrl), ACTION_OPEN_URL_MAX_LENGTH);
+    const desktopOpenSshForward = clamp(trimmedString(entry.desktopOpenSshForward), ACTION_DESKTOP_FORWARD_MAX_LENGTH);
+
+    const action = { id, name, command, icon: icon || null };
+    if (entry.autoOpenUrl === true) action.autoOpenUrl = true;
+    if (openUrl) action.openUrl = openUrl;
+    if (desktopOpenSshForward) action.desktopOpenSshForward = desktopOpenSshForward;
+    if (platforms.length > 0) action.platforms = platforms;
+    if (entry.runIn === 'parent') action.runIn = 'parent';
+    actions.push(action);
+  }
+  return actions;
+};
+
+/** Draft starters: `{ type: 'command' | 'skill', name }`, unique by `type:name`. */
+export const sanitizeDraftStarters = (value) => {
+  if (!Array.isArray(value)) return [];
+  const starters = [];
+  const seen = new Set();
+  for (const entry of value) {
+    if (!isObjectRecord(entry)) continue;
+    const type = entry.type === 'command' || entry.type === 'skill' ? entry.type : null;
+    const name = trimmedString(entry.name);
+    if (!type || !name) continue;
+    const key = `${type}:${name}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    starters.push({ type, name });
+  }
+  return starters;
+};
+
+/**
+ * The client-facing view of a raw config document. A primary action id that
+ * names no action is reported as `null`.
+ */
+const sanitizeIdList = (value) => {
+  if (!Array.isArray(value)) return [];
+  const ids = [];
+  for (const entry of value) {
+    const id = trimmedString(entry);
+    if (id && !ids.includes(id)) ids.push(id);
+  }
+  return ids;
+};
+
+/**
+ * The personal part of the view, straight from the personal file. The wait
+ * flag is `null` when the file does not set it, so the merge can let a
+ * shared value through; `hiddenSharedActionIds` and `setupWorktreeMode` only
+ * matter when a shared file exists.
+ */
+export const projectSetupViewOf = (raw) => {
+  const document = isObjectRecord(raw) ? raw : {};
+  const projectActions = sanitizeProjectActions(document.projectActions);
+  const primaryRaw = trimmedString(document.projectActionsPrimaryId);
+  return {
+    setupWorktree: sanitizeSetupCommands(document['setup-worktree']),
+    setupWorktreeWait: typeof document['setup-worktree-wait'] === 'boolean' ? document['setup-worktree-wait'] : null,
+    setupWorktreeMode: SETUP_WORKTREE_MODES.has(document.setupWorktreeMode) ? document.setupWorktreeMode : 'append',
+    projectActions,
+    projectActionsPrimaryId: primaryRaw && projectActions.some((action) => action.id === primaryRaw) ? primaryRaw : null,
+    draftStarters: sanitizeDraftStarters(document.draftStarters),
+    hiddenSharedActionIds: sanitizeIdList(document.hiddenSharedActionIds),
+    sharedTrust: sharedTrustOf(document.sharedTrust),
+  };
+};
+
+/** The recorded answer to the trust prompt: which shared commands were trusted, and when. */
+const sharedTrustOf = (value) => {
+  if (!isObjectRecord(value)) return null;
+  const hash = trimmedString(value.hash);
+  if (!hash) return null;
+  return { hash, trustedAt: Number.isFinite(value.trustedAt) ? value.trustedAt : 0 };
+};
+
+/**
+ * Turn a client patch (view keys) into the on-disk keys it changes. Only the
+ * keys present in the patch are returned, so a caller can merge the result
+ * over the raw document without clearing what the patch did not mention.
+ * A key with the wrong shape is a validation error, never silently dropped.
+ */
+export const projectSetupPatchToStored = (patch) => {
+  if (!isObjectRecord(patch)) {
+    throw new Error('patch must be an object');
+  }
+  const stored = {};
+  if ('setupWorktree' in patch) {
+    if (!Array.isArray(patch.setupWorktree)) throw new Error('setupWorktree must be an array of commands');
+    stored['setup-worktree'] = sanitizeSetupCommands(patch.setupWorktree);
+  }
+  if ('setupWorktreeWait' in patch) {
+    if (typeof patch.setupWorktreeWait !== 'boolean') throw new Error('setupWorktreeWait must be a boolean');
+    stored['setup-worktree-wait'] = patch.setupWorktreeWait;
+  }
+  if ('projectActions' in patch) {
+    if (!Array.isArray(patch.projectActions)) throw new Error('projectActions must be an array');
+    stored.projectActions = sanitizeProjectActions(patch.projectActions);
+  }
+  if ('projectActionsPrimaryId' in patch) {
+    const primary = patch.projectActionsPrimaryId;
+    if (primary !== null && typeof primary !== 'string') throw new Error('projectActionsPrimaryId must be a string or null');
+    stored.projectActionsPrimaryId = trimmedString(primary) || undefined;
+  }
+  if ('draftStarters' in patch) {
+    if (!Array.isArray(patch.draftStarters)) throw new Error('draftStarters must be an array');
+    stored.draftStarters = sanitizeDraftStarters(patch.draftStarters);
+  }
+  if ('hiddenSharedActionIds' in patch) {
+    if (!Array.isArray(patch.hiddenSharedActionIds)) throw new Error('hiddenSharedActionIds must be an array');
+    stored.hiddenSharedActionIds = sanitizeIdList(patch.hiddenSharedActionIds);
+  }
+  if ('setupWorktreeMode' in patch) {
+    if (!SETUP_WORKTREE_MODES.has(patch.setupWorktreeMode)) throw new Error('setupWorktreeMode must be "append" or "replace"');
+    stored.setupWorktreeMode = patch.setupWorktreeMode;
+  }
+  if ('sharedTrustHash' in patch) {
+    const hash = patch.sharedTrustHash;
+    if (hash !== null && (typeof hash !== 'string' || !hash.trim())) throw new Error('sharedTrustHash must be a non-empty string or null');
+    stored.sharedTrust = hash === null ? undefined : { hash: hash.trim(), trustedAt: Date.now() };
+  }
+  if ('projectPath' in patch) {
+    if (typeof patch.projectPath !== 'string') throw new Error('projectPath must be a string');
+    const projectPath = patch.projectPath.trim();
+    if (projectPath) stored.projectPath = projectPath;
+  }
+  return stored;
+};
+
+// ── Shared file ──
+
+export const SHARED_CONFIG_RELATIVE_PATH = '.aiworker/project.json';
+/** Where repository plans live unless the shared file's `plansDir` says otherwise. */
+export const DEFAULT_PLANS_DIR = '.aiworker/plans';
+const SHARED_CONFIG_VERSION = 1;
+
+/**
+ * A `plansDir` is a relative path inside the repo: no absolute paths, no
+ * drive letters, no `..` segments, forward slashes. Returns the normalized
+ * value or `null` when the value is not acceptable.
+ */
+export const normalizePlansDir = (value) => {
+  const raw = trimmedString(value).replace(/\\/g, '/');
+  if (!raw) return null;
+  if (raw.startsWith('/') || /^[A-Za-z]:/.test(raw)) return null;
+  const segments = raw.split('/').filter((segment) => segment.length > 0 && segment !== '.');
+  if (segments.length === 0 || segments.some((segment) => segment === '..')) return null;
+  return segments.join('/');
+};
+
+const EMPTY_SHARED = Object.freeze({
+  setupWorktree: [],
+  setupWorktreeWait: null,
+  projectActions: [],
+  draftStarters: [],
+  plansDir: null,
+});
+
+/**
+ * Parse the text of a shared file. Anything that is not a version-1 object
+ * is `invalid` with a reason (never an empty config: a teammate must see that
+ * the file is broken, not that the project has no shared setup). A `plansDir`
+ * that points outside the repo is invalid for the same reason.
+ */
+export const parseSharedProjectConfig = (raw) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    return { status: 'invalid', reason: `invalid JSON: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  if (!isObjectRecord(parsed)) return { status: 'invalid', reason: 'not an object' };
+  if (parsed.version !== SHARED_CONFIG_VERSION) return { status: 'invalid', reason: `unsupported version ${JSON.stringify(parsed.version)}` };
+  if ('setupWorktree' in parsed && !Array.isArray(parsed.setupWorktree)) return { status: 'invalid', reason: 'setupWorktree must be an array' };
+  if ('setupWorktreeWait' in parsed && typeof parsed.setupWorktreeWait !== 'boolean') return { status: 'invalid', reason: 'setupWorktreeWait must be a boolean' };
+  if ('projectActions' in parsed && !Array.isArray(parsed.projectActions)) return { status: 'invalid', reason: 'projectActions must be an array' };
+  if ('draftStarters' in parsed && !Array.isArray(parsed.draftStarters)) return { status: 'invalid', reason: 'draftStarters must be an array' };
+  let plansDir = null;
+  if ('plansDir' in parsed && parsed.plansDir !== null) {
+    plansDir = normalizePlansDir(parsed.plansDir);
+    if (!plansDir) return { status: 'invalid', reason: 'plansDir must be a relative path inside the repository' };
+  }
+  return {
+    status: 'ok',
+    config: {
+      setupWorktree: sanitizeSetupCommands(parsed.setupWorktree),
+      setupWorktreeWait: typeof parsed.setupWorktreeWait === 'boolean' ? parsed.setupWorktreeWait : null,
+      projectActions: sanitizeProjectActions(parsed.projectActions),
+      draftStarters: sanitizeDraftStarters(parsed.draftStarters),
+      plansDir,
+    },
+  };
+};
+
+const withSource = (entries, source) => entries.map((entry) => ({ ...entry, source }));
+
+/**
+ * What a trust answer covers: the shared setup commands and the shared
+ * actions' commands, in a canonical order, hashed. A pull that changes any
+ * of them changes the hash, so the prompt returns for the new commands.
+ * `null` when the shared config has nothing that executes.
+ */
+export const sharedTrustHashOf = (shared) => {
+  const commands = shared.setupWorktree;
+  const actions = shared.projectActions
+    .map((action) => {
+      const executable = { id: action.id, command: action.command };
+      if (action.runIn) executable.runIn = action.runIn;
+      return executable;
+    })
+    .sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+  if (commands.length === 0 && actions.length === 0) return null;
+  const digest = crypto.createHash('sha256').update(JSON.stringify({ setupWorktree: commands, projectActions: actions })).digest('hex');
+  return `sha256:${digest}`;
+};
+
+/**
+ * One merged view from the personal view and the shared read. Rules:
+ * - setup commands: shared first, then personal; personal `setupWorktreeMode`
+ *   `replace` uses only the personal list;
+ * - wait flag: personal when the personal file sets it, else shared, else off;
+ * - actions: union by id, a personal action replaces the shared one with the
+ *   same id, hidden shared ids are dropped, primary is personal only;
+ * - draft starters: union by `type:name`, shared first.
+ * Every merged action and starter carries `source`. The `shared` and
+ * `personal` blocks are returned too so a page can edit one without guessing
+ * which entries came from where.
+ */
+export const mergeProjectSetup = (personal, sharedRead) => {
+  const shared = sharedRead.status === 'ok' ? sharedRead.config : EMPTY_SHARED;
+  const hidden = new Set(personal.hiddenSharedActionIds);
+  const personalIds = new Set(personal.projectActions.map((action) => action.id));
+  const sharedActions = shared.projectActions.filter((action) => !hidden.has(action.id) && !personalIds.has(action.id));
+  const starterKeys = new Set(shared.draftStarters.map((starter) => `${starter.type}:${starter.name}`));
+  const personalStarters = personal.draftStarters.filter((starter) => !starterKeys.has(`${starter.type}:${starter.name}`));
+  const trustHash = sharedTrustHashOf(shared);
+  return {
+    // Nothing executable in the shared file means nothing to trust; otherwise
+    // the recorded answer must match the current commands exactly.
+    trust: { hash: trustHash, trusted: trustHash === null || personal.sharedTrust?.hash === trustHash },
+    setupWorktree: personal.setupWorktreeMode === 'replace'
+      ? personal.setupWorktree
+      : [...shared.setupWorktree, ...personal.setupWorktree],
+    setupWorktreeWait: personal.setupWorktreeWait !== null
+      ? personal.setupWorktreeWait
+      : shared.setupWorktreeWait === true,
+    projectActions: [...withSource(sharedActions, 'shared'), ...withSource(personal.projectActions, 'personal')],
+    projectActionsPrimaryId: personal.projectActionsPrimaryId,
+    draftStarters: [...withSource(shared.draftStarters, 'shared'), ...withSource(personalStarters, 'personal')],
+    shared: sharedBlockOf(sharedRead, shared),
+    personal,
+  };
+};
+
+const sharedBlockOf = (sharedRead, shared) => {
+  const block = { status: sharedRead.status, path: SHARED_CONFIG_RELATIVE_PATH, ...shared };
+  if (sharedRead.status === 'invalid') block.reason = sharedRead.reason;
+  return block;
+};
+
+/** An action without an icon is written without the key; readers fall back to the play icon. */
+const withoutEmptyIcon = (action) => {
+  if (action.icon !== null) return action;
+  const { icon: _emptyIcon, ...rest } = action;
+  return rest;
+};
+
+/** True when the shared config carries nothing: the file should not exist. */
+export const isSharedProjectConfigEmpty = (config) => (
+  config.setupWorktree.length === 0
+  && config.setupWorktreeWait === null
+  && config.projectActions.length === 0
+  && config.draftStarters.length === 0
+  && config.plansDir === null
+);
+
+/**
+ * The bytes of a shared file: version first, then only the keys that carry
+ * something, in a fixed order, pretty-printed — the file is committed and
+ * reviewed, so its diffs must stay readable. Actions lose their `source`
+ * mark and keep only the fields the user set.
+ */
+export const serializeSharedProjectConfig = (config) => {
+  const document = { version: SHARED_CONFIG_VERSION };
+  if (config.setupWorktree.length > 0) document.setupWorktree = config.setupWorktree;
+  if (config.setupWorktreeWait !== null) document.setupWorktreeWait = config.setupWorktreeWait;
+  if (config.projectActions.length > 0) document.projectActions = sanitizeProjectActions(config.projectActions).map(withoutEmptyIcon);
+  if (config.draftStarters.length > 0) document.draftStarters = config.draftStarters;
+  if (config.plansDir !== null) document.plansDir = config.plansDir;
+  return `${JSON.stringify(document, null, 2)}\n`;
+};
+
+/**
+ * The next shared config after a client patch over the current one. Every
+ * named key replaces the current value; a wrongly shaped key is a validation
+ * error, and a `plansDir` outside the repo is refused rather than stored.
+ */
+export const applySharedProjectSetupPatch = (current, patch) => {
+  if (!isObjectRecord(patch)) throw new Error('patch must be an object');
+  const next = { ...current };
+  if ('setupWorktree' in patch) {
+    if (!Array.isArray(patch.setupWorktree)) throw new Error('setupWorktree must be an array of commands');
+    next.setupWorktree = sanitizeSetupCommands(patch.setupWorktree);
+  }
+  if ('setupWorktreeWait' in patch) {
+    if (patch.setupWorktreeWait !== null && typeof patch.setupWorktreeWait !== 'boolean') throw new Error('setupWorktreeWait must be a boolean or null');
+    next.setupWorktreeWait = patch.setupWorktreeWait;
+  }
+  if ('projectActions' in patch) {
+    if (!Array.isArray(patch.projectActions)) throw new Error('projectActions must be an array');
+    next.projectActions = sanitizeProjectActions(patch.projectActions);
+  }
+  if ('draftStarters' in patch) {
+    if (!Array.isArray(patch.draftStarters)) throw new Error('draftStarters must be an array');
+    next.draftStarters = sanitizeDraftStarters(patch.draftStarters);
+  }
+  if ('plansDir' in patch) {
+    if (patch.plansDir === null || (typeof patch.plansDir === 'string' && !patch.plansDir.trim())) {
+      next.plansDir = null;
+    } else {
+      const plansDir = normalizePlansDir(patch.plansDir);
+      if (!plansDir) throw new Error('plansDir must be a relative path inside the repository');
+      next.plansDir = plansDir;
+    }
+  }
+  return next;
+};
+
+export const EMPTY_SHARED_PROJECT_CONFIG = EMPTY_SHARED;
+
+export const isProjectSetupValidationError = (error) => {
+  const message = error instanceof Error ? error.message : '';
+  return message.includes('must be') || message.includes('is required') || message.includes('unsupported characters') || message.includes('not found');
+};