@vantran-se/openchamber-web 2.1.1 → 2.2.0

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

@@ -3,21 +3,6 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { createGlobalMessageStreamHub } from '../event-stream/global-hub.js';
 import { createOpenCodeWatcherRuntime } from './watcher.js';
 
-async function waitForAssertion(assertion) {
-  const deadline = Date.now() + 1000;
-  let lastError;
-  while (Date.now() < deadline) {
-    try {
-      assertion();
-      return;
-    } catch (error) {
-      lastError = error;
-      await new Promise((resolve) => setTimeout(resolve, 10));
-    }
-  }
-  throw lastError;
-}
-
 function createSseResponse({ blocks = [], signal, holdOpen = false }) {
   const encoder = new TextEncoder();
   let index = 0;
@@ -204,45 +189,6 @@ describe('createOpenCodeWatcherRuntime', () => {
     });
   });
 
-  it('keeps its shared subscription across a hub rebind', async () => {
-    vi.spyOn(console, 'log').mockImplementation(() => {});
-    let generation = 0;
-    const payloads = [];
-    const globalEventHub = createGlobalMessageStreamHub({
-      buildOpenCodeUrl: () => `http://127.0.0.1:${generation === 0 ? 4096 : 5096}/api/event`,
-      getOpenCodeAuthHeaders: () => ({ Authorization: generation === 0 ? 'Basic first' : 'Basic second' }),
-      upstreamReconnectDelayMs: 60_000,
-      fetchImpl: async (_url, options) => createSseResponse({
-        signal: options.signal,
-        holdOpen: true,
-        blocks: [generation === 0
-          ? 'data: {"id":"evt-1","type":"server.connected","data":{}}\n\n'
-          : 'data: {"id":"evt-2","type":"session.renamed","location":{"directory":"/tmp/project"},"data":{"sessionID":"ses_1","title":"Recovered"}}\n\n'],
-      }),
-    });
-    const watcher = createOpenCodeWatcherRuntime({
-      waitForOpenCodePort: async () => {},
-      buildOpenCodeUrl: () => '',
-      getOpenCodeAuthHeaders: () => ({}),
-      globalEventHub,
-      onPayload: (payload) => payloads.push(payload),
-    });
-
-    try {
-      await watcher.start();
-      await waitForAssertion(() => expect(payloads.map((payload) => payload.type)).toContain('server.connected'));
-      generation = 1;
-      globalEventHub.rebind();
-      await waitForAssertion(() => expect(payloads).toContainEqual(expect.objectContaining({
-        type: 'session.updated',
-        properties: expect.objectContaining({ sessionID: 'ses_1' }),
-      })));
-    } finally {
-      watcher.stop();
-      globalEventHub.stop();
-    }
-  });
-
   it('does not stop a shared global event hub when the watcher stops', async () => {
     const events = new Set();
     const statuses = new Set();

package/server/lib/outbound-proxy.js

@@ -0,0 +1,52 @@
+import http from 'node:http';
+
+// Outbound requests from the server follow the standard proxy variables
+// (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, either case), so usage quotas, catalogs
+// and other upstream calls work behind a corporate or local proxy without
+// NODE_USE_ENV_PROXY. Loopback always stays direct: OAuth callbacks, the
+// managed OpenCode server and SSH forwards live there, and a proxy that
+// cannot reach this machine's 127.0.0.1 would break them.
+
+const LOOPBACK_HOSTS = ['localhost', '127.0.0.1', '::1'];
+
+const readVariable = (env, name) => String(env[name] ?? env[name.toLowerCase()] ?? '').trim();
+
+/**
+ * The proxy settings the environment asks for, with loopback added to the
+ * bypass list, or null when no proxy is configured.
+ */
+export const resolveOutboundProxyEnv = (env) => {
+  const httpProxy = readVariable(env, 'HTTP_PROXY');
+  const httpsProxy = readVariable(env, 'HTTPS_PROXY');
+  if (!httpProxy && !httpsProxy) return null;
+  const bypass = readVariable(env, 'NO_PROXY').split(',').map((entry) => entry.trim()).filter(Boolean);
+  for (const host of LOOPBACK_HOSTS) {
+    if (!bypass.includes(host)) bypass.push(host);
+  }
+  const proxyEnv = { NO_PROXY: bypass.join(',') };
+  if (httpProxy) proxyEnv.HTTP_PROXY = httpProxy;
+  if (httpsProxy) proxyEnv.HTTPS_PROXY = httpsProxy;
+  return proxyEnv;
+};
+
+/**
+ * Route this process's fetch and http(s) requests through the configured
+ * proxy. NO_PROXY is written back to the environment so clients that read it
+ * themselves (Bun's fetch, child processes) keep loopback direct too.
+ * Returns whether a proxy was configured.
+ */
+export const applyOutboundProxyFromEnv = ({ env = process.env, httpModule = http } = {}) => {
+  const proxyEnv = resolveOutboundProxyEnv(env);
+  if (!proxyEnv) return false;
+  env.NO_PROXY = proxyEnv.NO_PROXY;
+  env.no_proxy = proxyEnv.NO_PROXY;
+  // Node 24 and Electron's Node apply this to fetch and http(s); Bun's fetch
+  // reads the variables directly.
+  try {
+    httpModule.setGlobalProxyFromEnv?.(proxyEnv);
+  } catch (error) {
+    console.warn('Could not apply the proxy from HTTP_PROXY/HTTPS_PROXY:', error?.message || error);
+    return false;
+  }
+  return true;
+};

package/server/lib/outbound-proxy.test.js

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from 'vitest';
+import { spawnSync } from 'node:child_process';
+
+import { applyOutboundProxyFromEnv, resolveOutboundProxyEnv } from './outbound-proxy.js';
+
+describe('resolveOutboundProxyEnv', () => {
+  it('is null without a proxy', () => {
+    expect(resolveOutboundProxyEnv({ NO_PROXY: 'internal.example' })).toBeNull();
+  });
+
+  it('reads either case and always bypasses loopback', () => {
+    expect(resolveOutboundProxyEnv({ https_proxy: 'http://proxy:7897', no_proxy: 'corp.example, 127.0.0.1' })).toEqual({
+      HTTPS_PROXY: 'http://proxy:7897',
+      NO_PROXY: 'corp.example,127.0.0.1,localhost,::1',
+    });
+  });
+});
+
+describe('applyOutboundProxyFromEnv', () => {
+  it('leaves the process alone without a proxy', () => {
+    const setGlobalProxyFromEnv = vi.fn();
+    expect(applyOutboundProxyFromEnv({ env: {}, httpModule: { setGlobalProxyFromEnv } })).toBe(false);
+    expect(setGlobalProxyFromEnv).not.toHaveBeenCalled();
+  });
+
+  it('writes the loopback bypass back for clients that read the environment', () => {
+    const env = { HTTP_PROXY: 'http://proxy:3128' };
+    const setGlobalProxyFromEnv = vi.fn();
+    expect(applyOutboundProxyFromEnv({ env, httpModule: { setGlobalProxyFromEnv } })).toBe(true);
+    expect(env.NO_PROXY).toBe('localhost,127.0.0.1,::1');
+    expect(env.no_proxy).toBe('localhost,127.0.0.1,::1');
+    expect(setGlobalProxyFromEnv).toHaveBeenCalledWith({ HTTP_PROXY: 'http://proxy:3128', NO_PROXY: 'localhost,127.0.0.1,::1' });
+  });
+
+  it('sends fetch through the proxy and keeps loopback direct in a real Node process', () => {
+    const moduleUrl = new URL('./outbound-proxy.js', import.meta.url).href;
+    const result = spawnSync('node', ['--input-type=module', '--eval', `
+      import http from 'node:http';
+      import assert from 'node:assert/strict';
+      const seen = [];
+      const proxy = http.createServer((req, res) => res.end());
+      proxy.on('connect', (req, socket) => { seen.push('proxy ' + req.url); socket.end('HTTP/1.1 502 Bad Gateway\\r\\n\\r\\n'); });
+      const local = http.createServer((req, res) => { seen.push('direct'); res.end('ok'); });
+      await new Promise((resolve) => proxy.listen(0, '127.0.0.1', resolve));
+      await new Promise((resolve) => local.listen(0, '127.0.0.1', resolve));
+      const { applyOutboundProxyFromEnv } = await import(${JSON.stringify(moduleUrl)});
+      assert.equal(applyOutboundProxyFromEnv({ env: { HTTPS_PROXY: 'http://127.0.0.1:' + proxy.address().port, HTTP_PROXY: 'http://127.0.0.1:' + proxy.address().port } }), true);
+      await fetch('http://upstream.invalid/usage').catch(() => {});
+      assert.equal(await (await fetch('http://127.0.0.1:' + local.address().port + '/')).text(), 'ok');
+      assert.deepEqual(seen, ['proxy upstream.invalid:80', 'direct']);
+      process.exit(0);
+    `], { encoding: 'utf8', timeout: 15_000, windowsHide: true });
+    expect(result.status, result.stderr).toBe(0);
+  });
+});

package/server/lib/package-manager.js

@@ -16,6 +16,7 @@ const PACKAGE_NAME = '@vantran-se/openchamber-web';
 const PACKAGE_PATH_SEGMENTS = PACKAGE_NAME.split('/');
 const GITHUB_RELEASES_URL = 'https://github.com/vantran-se/openchamber/releases';
 const GITHUB_RELEASES_API_URL = 'https://api.github.com/repos/vantran-se/openchamber/releases';
+const UPSTREAM_RELEASES_API_URL = 'https://api.github.com/repos/openchamber/openchamber/releases';
 let cachedDetectedPm = null;
 
 function getSpawnSyncBaseOptions() {
@@ -98,7 +99,7 @@ async function resolveAndroidApkUrl(version, candidateUrl) {
   }
 
   try {
-    const response = await fetch(`${GITHUB_RELEASES_API_URL}/tags/v${version}`, {
+    const response = await fetch(`${UPSTREAM_RELEASES_API_URL}/tags/v${version}`, {
       headers: {
         Accept: 'application/vnd.github+json',
         'User-Agent': 'openchamber-update-check',
@@ -600,6 +601,15 @@ function resolvePackageManagerCommand(pm) {
   return pm;
 }
 
+function quoteCommand(command) {
+  if (!command) return command;
+  if (!/\s/.test(command)) return command;
+  if (process.platform === 'win32') {
+    return `"${command.replace(/"/g, '""')}"`;
+  }
+  return `'${command.replace(/'/g, "'\\''")}'`;
+}
+
 function isCommandAvailable(command) {
   try {
     const result = spawnSync(command, ['--version'], {
@@ -648,7 +658,7 @@ function isPackageInstalledWith(pm) {
 
 // npm, bun and yarn print `name@version`; pnpm separates the name and the
 // version with whitespace. An optional `v` covers yarn listing formats.
-const GLOBAL_VERSION_PATTERN = /@vantran-se\/openchamber-web[@\s]+v?(\d[\w.+-]*)/;
+const GLOBAL_VERSION_PATTERN = /(?:@vantran-se\/openchamber-web|@openchamber\/web)[@\s]+v?(\d[\w.+-]*)/;
 
 /**
  * Read the globally installed version of the package as reported by the
@@ -687,30 +697,25 @@ function normalizeTargetVersion(value) {
  * package manager see different metadata, and dist-tag resolution can lag the
  * check behind a fresh release (stale packument cache, pnpm minimumReleaseAge).
  */
-function getUpdateInvocation(pm = detectPackageManager(), options = {}) {
+export function getUpdateCommand(pm = detectPackageManager(), options = {}) {
   const targetVersion = normalizeTargetVersion(options.targetVersion);
   if (options.targetVersion != null && !targetVersion) {
     throw new Error(`Invalid target version for update: ${String(options.targetVersion)}`);
   }
-  const packageSpec = `${PACKAGE_NAME}@${targetVersion || 'latest'}`;
-  const command = resolvePackageManagerCommand(pm);
+  const versionSpec = targetVersion ? `@${targetVersion}` : '@latest';
+  const pmCommand = quoteCommand(resolvePackageManagerCommand(pm));
   switch (pm) {
     case 'pnpm':
-      return { command, args: ['add', '-g', packageSpec] };
+      return `${pmCommand} add -g ${PACKAGE_NAME}${versionSpec}`;
     case 'yarn':
-      return { command, args: ['global', 'add', packageSpec] };
+      return `${pmCommand} global add ${PACKAGE_NAME}${versionSpec}`;
     case 'bun':
-      return { command, args: ['add', '-g', packageSpec] };
+      return `${pmCommand} add -g ${PACKAGE_NAME}${versionSpec}`;
     default:
-      return { command, args: ['install', '-g', packageSpec] };
+      return `${pmCommand} install -g ${PACKAGE_NAME}${versionSpec}`;
   }
 }
 
-export function getUpdateCommand(pm = detectPackageManager(), options = {}) {
-  const invocation = getUpdateInvocation(pm, options);
-  return [invocation.command, ...invocation.args].join(' ');
-}
-
 /**
  * Get current installed version from package.json
  */
@@ -850,14 +855,15 @@ export async function checkForUpdates(options = {}) {
  * and the caller must not report success without the version matching.
  */
 export function executeUpdate(pm = detectPackageManager(), options = {}) {
-  const invocation = getUpdateInvocation(pm, { targetVersion: options.targetVersion });
+  const command = getUpdateCommand(pm, { targetVersion: options.targetVersion });
   if (!options?.silent) {
     console.log(`Updating ${PACKAGE_NAME} using ${pm}...`);
-    console.log(`Running: ${[invocation.command, ...invocation.args].join(' ')}`);
+    console.log(`Running: ${command}`);
   }
 
-  const result = spawnSync(invocation.command, invocation.args, {
+  const result = spawnSync(command, {
     stdio: 'inherit',
+    shell: true,
     ...getSpawnSyncBaseOptions(),
   });
 

package/server/lib/package-manager.test.js

@@ -39,22 +39,6 @@ function createFetchMock() {
   return mock;
 }
 
-describe('fork package update command', () => {
-  it('targets the published fork without a runtime environment override', () => {
-    expect(getUpdateCommand('npm')).toBe('npm install -g @vantran-se/openchamber-web@latest');
-  });
-
-  it('executes the package manager without a shell', () => {
-    spawnSync.mockClear();
-    executeUpdate('npm', { silent: true });
-    expect(spawnSync).toHaveBeenCalledWith(
-      'npm',
-      ['install', '-g', '@vantran-se/openchamber-web@latest'],
-      expect.not.objectContaining({ shell: true }),
-    );
-  });
-});
-
 describe('checkForUpdates', () => {
   let fetchMock;
   let originalFetch;
@@ -277,7 +261,7 @@ describe('checkForUpdates', () => {
           downloadUrl: 'https://github.com/openchamber/openchamber/releases/download/v1.10.0/OpenChamber-1.10.0-42-android.aab',
         }),
       })
-      .when('api.github.com/repos/vantran-se/openchamber/releases/tags/v1.10.0', {
+      .when('api.github.com/repos/openchamber/openchamber/releases/tags/v1.10.0', {
         ok: true,
         json: async () => ({
           assets: [
@@ -463,13 +447,16 @@ describe('getUpdateCommand', () => {
 describe('executeUpdate', () => {
   function stubSpawnSync({ installStatus = 0, listingStdout = '', listingStatus = 0 } = {}) {
     spawnSync.mockImplementation((command, args) => {
+      if (!Array.isArray(args)) {
+        return { status: installStatus, stdout: '', stderr: '' };
+      }
       if (args.includes('--version')) {
         return { status: 0, stdout: '10.0.0', stderr: '' };
       }
       if (args[0] === 'list' || args[0] === 'pm' || args[0] === 'global') {
         return { status: listingStatus, stdout: listingStdout, stderr: '' };
       }
-      return { status: installStatus, stdout: '', stderr: '' };
+      return { status: 0, stdout: '', stderr: '' };
     });
   }
 

package/server/lib/permission-auto-accept/DOCUMENTATION.md

@@ -18,7 +18,7 @@ Policies written before the modes stored booleans. The first read converts them
 
 ## Default mode
 
-`permissionDefaultMode` (Settings → Sessions) is written onto each top-level session when OpenChamber adopts it (`metadata.openchamber.adopted === true` arrives through `session.created` or `session.updated`), and only when no policy exists for it yet: a mode the creating flow already set wins, and changing the default never reaches back into older sessions. A session seen only through the shared local OpenCode service remains TUI-owned, so Web settings cannot silently change its permission policy. OpenChamber creation and the first message sent from an OpenChamber surface persist the adoption marker; merely viewing a session does not. Subagents inherit instead. `ask` is persisted too, so a later change to the global default cannot retroactively change an existing session. Mode resolution waits for pending writes on the session and its ancestors, so an adopted session's first permission request sees its default.
+`permissionDefaultMode` (Settings → Sessions) is written onto each new top-level session when `session.created` arrives, and only when no policy exists for it yet: a mode the creating flow already set wins, and changing the default never reaches back into older sessions. Subagents inherit instead. `ask` writes nothing. Mode resolution waits for pending writes, so a session's first permission request sees its default.
 
 ## Runtime
 

package/server/lib/permission-auto-accept/runtime.js

@@ -18,13 +18,7 @@ const storedPolicySchema = z.object({
 
 const readStoredPolicy = (value) => storedPolicySchema.parse(value ?? {});
 
-const createdSessionSchema = z.object({
-  id: z.string().min(1),
-  parentID: z.string().nullish(),
-  metadata: z.object({
-    openchamber: z.object({ adopted: z.literal(true).optional() }).optional(),
-  }).optional(),
-});
+const createdSessionSchema = z.object({ id: z.string().min(1), parentID: z.string().nullish() });
 
 const hasLegacyEntries = (stored) => Object.values(stored.sessions).some((entry) => entry === true || entry === false);
 
@@ -148,29 +142,17 @@ export function createPermissionAutoAcceptRuntime({
    * sessions; a policy the creating flow already set wins. Subagents inherit
    * from their parent instead.
    */
-  const defaultModePromises = new Map();
-  const applyDefaultMode = (sessionId, resolveParentID = async () => null) => {
-    const existing = defaultModePromises.get(sessionId);
-    if (existing) return existing;
-    const pending = (async () => {
-      const parentID = await resolveParentID();
-      if (parentID !== null) return;
-      await load();
-      if (Object.hasOwn(policy.sessions, sessionId)) return;
-      const settings = await readSettingsFromDiskMigrated();
-      const configuredMode = settings?.[DEFAULT_MODE_SETTINGS_KEY];
-      const mode = isPermissionMode(configuredMode) ? configuredMode : 'ask';
-      await persistUpdate((current) => (Object.hasOwn(current.sessions, sessionId) ? current : {
-        ...current,
-        sessions: { ...current.sessions, [sessionId]: mode },
-        revision: current.revision + 1,
-      }));
-    })();
-    defaultModePromises.set(sessionId, pending);
-    void pending.finally(() => {
-      if (defaultModePromises.get(sessionId) === pending) defaultModePromises.delete(sessionId);
-    });
-    return pending;
+  const applyDefaultMode = async (sessionId) => {
+    await load();
+    if (Object.hasOwn(policy.sessions, sessionId)) return;
+    const settings = await readSettingsFromDiskMigrated();
+    const mode = settings?.[DEFAULT_MODE_SETTINGS_KEY];
+    if (!isPermissionMode(mode) || mode === 'ask') return;
+    await persistUpdate((current) => (Object.hasOwn(current.sessions, sessionId) ? current : {
+      ...current,
+      sessions: { ...current.sessions, [sessionId]: mode },
+      revision: current.revision + 1,
+    }));
   };
 
   const rememberSession = (info, directoryHint) => {
@@ -178,9 +160,7 @@ export function createPermissionAutoAcceptRuntime({
     // v2 session updates are partial (a rename carries only the title), so a
     // field the update does not name keeps what an earlier record said.
     const previous = sessions.get(info.id);
-    const parentID = typeof info.parentID === 'string' && info.parentID
-      ? info.parentID
-      : (previous ? previous.parentID : undefined);
+    const parentID = typeof info.parentID === 'string' && info.parentID ? info.parentID : previous?.parentID ?? null;
     // v2 keeps the directory on `location`; translated events already flatten it.
     const directory = typeof info.directory === 'string' && info.directory
       ? info.directory
@@ -219,7 +199,7 @@ export function createPermissionAutoAcceptRuntime({
 
   const getSession = async (sessionId, directory) => {
     const cached = sessions.get(sessionId);
-    if (cached?.parentID !== undefined) return cached;
+    if (cached) return cached;
     const info = await request(`/api/session/${encodeURIComponent(sessionId)}`, { directory });
     rememberSession(info?.data ?? info, directory);
     return sessions.get(sessionId) ?? null;
@@ -228,16 +208,13 @@ export function createPermissionAutoAcceptRuntime({
   /** The nearest explicit mode up the session's lineage; unknown lineage fails closed to `ask`. */
   const resolveSessionMode = async (sessionId, directory) => {
     await load();
-    // A default being selected and written for a newly adopted session must be
-    // visible to its first permission request.
-    await defaultModePromises.get(sessionId)?.catch(() => undefined);
+    // A default being written for a just-created session must be visible to
+    // its first permission request.
     await writePromise.catch(() => undefined);
     const seen = new Set();
     let current = sessionId;
     let currentDirectory = directory;
     while (current && !seen.has(current)) {
-      await defaultModePromises.get(current)?.catch(() => undefined);
-      await writePromise.catch(() => undefined);
       if (Object.hasOwn(policy.sessions, current)) return policy.sessions[current];
       seen.add(current);
       let info;
@@ -375,14 +352,9 @@ export function createPermissionAutoAcceptRuntime({
       if (payload.type === 'session.created' || payload.type === 'session.updated') {
         const info = payload.properties?.info;
         rememberSession(info, directory ?? payload.properties?.directory);
-        const adopted = createdSessionSchema.safeParse(info);
-        const remembered = adopted.success ? sessions.get(adopted.data.id) : null;
-        if (adopted.success && adopted.data.metadata?.openchamber?.adopted === true) {
-          void applyDefaultMode(adopted.data.id, async () => {
-            const parentID = remembered?.parentID;
-            if (parentID !== undefined) return parentID;
-            return (await getSession(adopted.data.id, remembered?.directory))?.parentID ?? null;
-          }).catch((error) => {
+        const created = payload.type === 'session.created' ? createdSessionSchema.safeParse(info) : null;
+        if (created?.success && !created.data.parentID) {
+          void applyDefaultMode(created.data.id).catch((error) => {
             console.warn('[permission-auto-accept] failed to apply the default mode:', error?.message ?? error);
           });
         }

package/server/lib/permission-auto-accept/runtime.test.js

@@ -77,11 +77,11 @@ describe('permission auto-accept runtime', () => {
     expect(resolveLegacyEnabledMode).toHaveBeenCalledTimes(1);
   });
 
-  it('writes the default mode onto a new OpenChamber-owned top-level session only', async () => {
+  it('writes the default mode onto a new top-level session only', async () => {
     const { runtime, emit, getSettings } = createRuntime();
     await runtime.load();
     getSettings().permissionDefaultMode = 'safety';
-    emit({ type: 'session.created', properties: { info: { id: 'root', metadata: { openchamber: { adopted: true } } } } });
+    emit({ type: 'session.created', properties: { info: { id: 'root' } } });
     emit({ type: 'session.created', properties: { info: { id: 'child', parentID: 'root' } } });
     await flush();
     await expect(runtime.resolveSessionMode('root', '/project')).resolves.toBe('safety');

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

@@ -100,7 +100,7 @@ collision gets a numeric suffix. Sharing is refused only when the checkout canno
 | PATCH | `/api/project-context/:projectId/notes/:noteId` | patches `body`; legacy `pinned` input is ignored by session knowledge; `404` when unknown |
 | DELETE | `/api/project-context/:projectId/notes/:noteId` | `404` when unknown |
 | PATCH | `/api/project-context/:projectId/plans/:planId` | legacy project pin state only; session attachment uses session knowledge; `404` when unknown |
-| GET | `/api/project-context/:projectId/plans/:planId` | `404` when the link or its markdown is gone |
+| GET | `/api/project-context/:projectId/plans/:planId` | `404` when the link or its markdown is gone; the answer carries `path`, the markdown's absolute path, so comments on the plan name the file to the agent (reads and writes stay id-addressed) |
 | 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 |
@@ -119,6 +119,12 @@ on a bare express app so that failure mode fails the suite instead of the user.
 separators and traversal. Validation failures are `400`; malformed stored data
 and I/O failures are `500`.
 
+## Change notifications
+
+After `writeContext` atomically commits `context.json`, the runtime calls its optional `onChanged(projectId)` dependency. The server broadcasts `openchamber:project-context-changed` with `{ projectId }` on the existing OpenChamber control stream. It carries the path-derived owner id, not the bounded storage stem or any note content. Failed writes and missing-entry no-ops announce nothing. Updating or deleting a shared plan through the API announces the same way after the file write, since shared plans have no manifest entry.
+
+Clients re-read authoritative context for the visible owner. This is a commit notification, not a filesystem watcher; direct changes to shared plan files outside the API retain their existing read-on-open behavior.
+
 ## Invariants
 
 - **Missing is not malformed.** A missing `context.json` is authoritative empty

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

@@ -13,12 +13,11 @@
  * undefined and rejects every write as a malformed body.
  */
 
+import { isRecord as isObjectRecord } from '../shared/guards.js';
 import express from 'express';
 
 const parseJsonBody = express.json({ limit: '1mb' });
 
-const isObjectRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-
 const isValidationError = (error) => {
   const message = error instanceof Error ? error.message : '';
   return message.includes('is required') || message.includes('unsupported characters');

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

@@ -12,12 +12,13 @@
  * directory never invalidates a reference.
  */
 
+import { asNonEmptyString, isRecord as isObjectRecord } from '../shared/guards.js';
 import { projectConfigFileStemOf } from '../projects/project-id.js';
 
 const PROJECT_CONTEXT_VERSION = 2;
 const PROJECT_NOTE_BODY_MAX_LENGTH = 3000;
 const PROJECT_NOTE_MAX_ITEMS = 200;
-const PROJECT_TODO_TEXT_MAX_LENGTH = 120;
+const PROJECT_TODO_TEXT_MAX_LENGTH = 1000;
 const PROJECT_PLAN_TITLE_MAX_LENGTH = 160;
 const PROJECT_PLAN_BODY_MAX_LENGTH = 200_000;
 const PROJECT_TODO_MAX_ITEMS = 500;
@@ -26,19 +27,11 @@ const PROJECT_PLAN_MAX_ITEMS = 500;
 const PROJECT_ID_PATTERN = /^[a-zA-Z0-9._:-]+$/;
 const PLAN_FILE_PATTERN = /^[a-zA-Z0-9._-]+\.md$/;
 
-const asNonEmptyString = (value) => {
-  if (typeof value !== 'string') return null;
-  const trimmed = value.trim();
-  return trimmed.length > 0 ? trimmed : null;
-};
-
 const clampLength = (value, maxLength) => {
   if (typeof value !== 'string') return '';
   return value.length > maxLength ? value.slice(0, maxLength) : value;
 };
 
-const isObjectRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-
 const NOTE_SOURCES = new Set(['manual', 'selection', 'agent']);
 
 const sanitizeNoteOrigin = (value) => {
@@ -197,7 +190,7 @@ const createEmptyContext = () => ({
 const SHARED_PLAN_ID_PREFIX = 'shared:';
 
 export const createProjectContextRuntime = (deps) => {
-  const { fsPromises, path, projectsDirPath, createId, resolveSharedPlansDir } = deps;
+  const { fsPromises, path, projectsDirPath, createId, resolveSharedPlansDir, onChanged } = 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'
@@ -473,6 +466,7 @@ export const createProjectContextRuntime = (deps) => {
       todos: context.todos,
       plans: context.plans,
     });
+    onChanged?.(sanitizeProjectId(projectId));
   };
 
   const saveTodos = async (projectId, todos) => {
@@ -586,15 +580,16 @@ export const createProjectContextRuntime = (deps) => {
     if (sharedFile) {
       const dir = await sharedPlansDirFor(projectId);
       if (!dir) return null;
+      const planPath = path.join(dir, sharedFile);
       let raw;
       try {
-        raw = await fsPromises.readFile(path.join(dir, sharedFile), 'utf8');
+        raw = await fsPromises.readFile(planPath, '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' };
+      return { id, file: sharedFile, path: planPath, 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);
@@ -604,16 +599,17 @@ export const createProjectContextRuntime = (deps) => {
 
     const folder = await folderOfLink(projectId, link);
     if (!folder) return null;
+    const planPath = path.join(folder, link.file);
     let raw;
     try {
-      raw = await fsPromises.readFile(path.join(folder, link.file), 'utf8');
+      raw = await fsPromises.readFile(planPath, '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, source: link.shared ? 'shared' : 'personal' };
+    return { id: link.id, file: link.file, path: planPath, createdAt: link.createdAt, title: parsed.title, body: parsed.body, raw, source: link.shared ? 'shared' : 'personal' };
   };
 
   /**
@@ -652,6 +648,7 @@ export const createProjectContextRuntime = (deps) => {
           throw error;
         }
         await fsPromises.writeFile(filePath, raw, 'utf8');
+        onChanged?.(sanitizeProjectId(projectId));
         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' };
@@ -771,6 +768,7 @@ export const createProjectContextRuntime = (deps) => {
         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 });
+        onChanged?.(sanitizeProjectId(projectId));
         return { deleted: true, context: await readContext(projectId) };
       });
     }