ompchamber 3.0.0 → 3.1.1

package/src/server/lib/bundler/nested-at-rules.ts

@@ -0,0 +1,146 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Hoist every nested at-rule out of the style rule that contains it.
+ *
+ * Bun's CSS minifier keeps the nesting it is handed, and for a target that is
+ * not the browser (`target: 'bun'`, which this build needs because its
+ * entrypoint is the SERVER) it re-nests a rule's nested at-rule into
+ * `@supports (…) { & { … } }`. Chrome does not apply a nested rule whose parent
+ * selector names a pseudo-element, so `&` under `::placeholder` or
+ * `::-webkit-scrollbar-thumb` is dropped and the rule's earlier fallback
+ * declaration wins instead — measured on the built bundle: the composer
+ * placeholder painted at full ink rather than 40%, every scrollbar thumb opaque
+ * rather than 20%.
+ *
+ * Tailwind v4 emits its colour fallbacks in exactly that shape (`color:
+ * var(--x); @supports (color: color-mix(…)) { color: color-mix(…) }`), so one
+ * minifier decision reached 16 rules: every placeholder utility in the app and
+ * every scrollbar rule, base and xterm included. The rsbuild pipeline this
+ * replaced compiled for browsers and flattened the nesting itself.
+ *
+ * Flattening here is what makes the bundle immune: the emitted CSS is
+ * `@supports (…) { .sel::placeholder { … } }` at the top level, which no
+ * minifier has anything left to re-nest and every browser applies. Declaration
+ * order is preserved exactly — a rule's declarations stay in the segments they
+ * were written in, and each at-rule is hoisted to the position it occupied — so
+ * the cascade is unchanged.
+ */
+
+import postcss from 'postcss';
+import type { AtRule, ChildNode, Container, Plugin, Rule } from 'postcss';
+
+/** Resolve a nested selector against the rule it was written inside. */
+function resolveSelector(parentSelector: string, nestedSelector: string): string {
+  if (nestedSelector.includes('&')) return nestedSelector.replaceAll('&', parentSelector);
+  return `${parentSelector} ${nestedSelector}`;
+}
+
+/**
+ * Resolve `&` in the rules directly inside `container`, descending through
+ * at-rules only: `&` still refers to the nearest enclosing STYLE rule, and an
+ * intermediate one is hoisted on a later pass.
+ *
+ * Runs BEFORE `wrapBareDeclarations` — the rule that wraps bare declarations
+ * already carries the parent's resolved selector, and resolving it again would
+ * turn `::placeholder` into `::placeholder ::placeholder`.
+ */
+function resolveAmpersands(container: Container, parentSelector: string): void {
+  for (const node of container.nodes ?? []) {
+    if (node.type === 'rule') node.selector = resolveSelector(parentSelector, node.selector);
+    else if (node.type === 'atrule') resolveAmpersands(node, parentSelector);
+  }
+}
+
+/** Wrap an at-rule's bare declarations in `parentSelector`, keeping them in place. */
+function wrapBareDeclarations(atRule: AtRule, parentSelector: string): void {
+  const nodes = [...(atRule.nodes ?? [])];
+  if (!nodes.some((node) => node.type === 'decl')) return;
+  const rebuilt: ChildNode[] = [];
+  let declarations: ChildNode[] = [];
+  const flush = () => {
+    if (declarations.length === 0) return;
+    const rule = postcss.rule({ selector: parentSelector });
+    rule.append(declarations);
+    rebuilt.push(rule);
+    declarations = [];
+  };
+  for (const node of nodes) {
+    if (node.type === 'decl') declarations.push(node);
+    else {
+      flush();
+      rebuilt.push(node);
+    }
+  }
+  flush();
+  atRule.removeAll();
+  atRule.append(rebuilt);
+}
+
+/** Hoist `rule`'s nested at-rules into its own container. Reports whether it moved any. */
+function hoistNestedAtRules(rule: Rule): boolean {
+  const container = rule.parent;
+  // Snapshot: reparenting the declarations empties `rule.nodes` mid-iteration.
+  const nodes = [...(rule.nodes ?? [])];
+  if (!container || !nodes.some((node) => node.type === 'atrule')) return false;
+
+  const replacement: ChildNode[] = [];
+  let declarations: ChildNode[] = [];
+  const flush = () => {
+    if (declarations.length === 0) return;
+    const segment = postcss.rule({ selector: rule.selector, raws: { ...rule.raws } });
+    segment.append(declarations);
+    replacement.push(segment);
+    declarations = [];
+  };
+
+  for (const node of nodes) {
+    if (node.type !== 'atrule') {
+      declarations.push(node);
+      continue;
+    }
+    flush();
+    const hoisted = node.clone();
+    resolveAmpersands(hoisted, rule.selector);
+    wrapBareDeclarations(hoisted, rule.selector);
+    replacement.push(hoisted);
+  }
+  flush();
+
+  container.insertBefore(rule, replacement);
+  rule.remove();
+  return true;
+}
+
+/**
+ * PostCSS plugin: hoist nested at-rules out of the rules containing them.
+ *
+ * `OnceExit` rather than `Once` so Tailwind's own pass has already expanded
+ * `@theme` and every utility before there is a rule to flatten; register it
+ * LAST for the same reason.
+ */
+export function flattenNestedAtRules(): Plugin {
+  return {
+    postcssPlugin: 'ompchamber-flatten-nested-at-rules',
+    OnceExit(root) {
+      // A hoist can expose another nested at-rule in the segment that received
+      // it, so repeat until a full pass moves nothing.
+      let hoisted = true;
+      while (hoisted) {
+        hoisted = false;
+        const rules: Rule[] = [];
+        root.walkRules((rule) => {
+          rules.push(rule);
+        });
+        // Reverse document order: a nested rule is walked after its parent, so
+        // the inner one is flattened first and its parent is then still intact.
+        for (let index = rules.length - 1; index >= 0; index -= 1) {
+          if (hoistNestedAtRules(rules[index])) hoisted = true;
+        }
+      }
+    },
+  };
+}

package/src/server/lib/lifecycle/launch-mode.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from 'bun:test';
 
-import { launchModeArg, resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
+import { isCliManaged, launchModeArg, resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
 
 const ENTRY = '/repo/src/server/index.ts';
 
@@ -30,3 +30,22 @@ describe('resolveLaunchMode', () => {
     }
   });
 });
+
+// Every command that would END a server decides with this predicate:
+// `restart`/`update` may replace it, and `stop` stops it by default. Guessing
+// wrong here kills a `bun run dev` the user owns — that launcher exits with its
+// child — or leaves a daemon serving the build that was just replaced.
+describe('isCliManaged', () => {
+  test('owns the instances the CLI started', () => {
+    expect(isCliManaged('daemon')).toBe(true);
+    expect(isCliManaged('foreground')).toBe(true);
+  });
+
+  test('leaves every instance OMPChamber did not start alone', () => {
+    // `bun run dev`, `bun run start`, a manual run, a systemd/pm2 unit.
+    expect(isCliManaged('direct')).toBe(false);
+    // A probed or unreadable record never authorises a kill either.
+    expect(isCliManaged('unknown')).toBe(false);
+    expect(isCliManaged(undefined)).toBe(false);
+  });
+});

package/src/server/lib/lifecycle/launch-mode.ts

@@ -38,3 +38,29 @@ export function resolveLaunchMode(argv: readonly string[] = Bun.argv): InstanceL
   const value = flag?.slice(LAUNCH_MODE_FLAG.length);
   return value === 'daemon' || value === 'foreground' ? value : 'direct';
 }
+
+/**
+ * Whether the CLI owns this instance's lifecycle — the one question every
+ * command that would end a server asks: `restart`/`update` may replace it, and
+ * `stop` stops it by default.
+ *
+ * A `direct` server runs under a launcher the CLI does not own, and that
+ * launcher exits with its child: `bun run dev` is a supervisor process whose
+ * only job is to mirror the script it spawned, so signalling the server ends
+ * the user's dev loop with it. Leaving those alone by default is what keeps
+ * `ompchamber stop` from killing a loop it did not start; an explicit
+ * `--port <port>` (or `--all`) still ends one, deliberately.
+ */
+export function isCliManaged(launchMode: string | null | undefined): boolean {
+  return launchMode === 'daemon' || launchMode === 'foreground';
+}
+
+/**
+ * Why an instance the CLI does not own is left alone, without the action. Each
+ * command that would end a server appends its own next step, so the two cannot
+ * describe the same `launchMode` differently.
+ */
+export function unmanagedReason(launchMode: string | null | undefined): string {
+  if (launchMode === 'direct') return 'runs from source (`bun run dev` / `bun run start`)';
+  return 'is not managed by the ompchamber CLI';
+}

package/src/server/lib/lifecycle/restart.ts

@@ -25,7 +25,7 @@ import { join as joinPath, resolve as resolvePath } from 'node:path';
 
 import { resolveBunBin } from '@/server/lib/lifecycle/bun';
 import { listInstanceRecords } from '@/server/lib/lifecycle/instance';
-import { resolveLaunchMode } from '@/server/lib/lifecycle/launch-mode';
+import { isCliManaged, resolveLaunchMode, unmanagedReason } from '@/server/lib/lifecycle/launch-mode';
 
 /** Package root of the running copy: src/server/lib/lifecycle -> four levels up. */
 const PKG_ROOT = resolvePath(import.meta.dir, '..', '..', '..', '..');
@@ -45,20 +45,15 @@ export interface SelfRestartPlan {
 }
 
 /**
- * True when the CLI owns this instance's lifecycle and may replace it. `direct`
- * is every server OMPChamber did not start: `bun run dev`, `bun run start`, a
- * manual `bun src/server/index.ts`, or an external supervisor.
+ * One-line reason an instance is left running, shared by the CLI and console.
+ * The clause comes from `unmanagedReason` so `stop`, `restart` and `update`
+ * cannot classify the same `launchMode` differently.
  */
-export function isAutoRestartable(launchMode: string | null | undefined): boolean {
-  return launchMode === 'daemon' || launchMode === 'foreground';
-}
-
-/** One-line reason an instance is left running, shared by the CLI and console. */
 export function skipRestartNote(launchMode: string | null | undefined): string {
-  if (launchMode === 'direct') {
-    return 'this instance runs from source (`bun run dev` / `bun run start`) — start it again to apply the update';
-  }
-  return 'this instance is not managed by the ompchamber CLI — restart it yourself to apply the update';
+  const nextStep = launchMode === 'direct'
+    ? 'start it again to apply the update'
+    : 'restart it yourself to apply the update';
+  return `this instance ${unmanagedReason(launchMode)} — ${nextStep}`;
 }
 
 /** The record this process wrote for itself; falls back to the env it was launched with. */
@@ -89,7 +84,7 @@ export function scheduleSelfRestart(): SelfRestartPlan {
     return { restarting: false, message: 'This instance could not be identified — restart it yourself to apply the update.' };
   }
 
-  if (!isAutoRestartable(self.launchMode)) {
+  if (!isCliManaged(self.launchMode)) {
     return { restarting: false, message: skipRestartNote(self.launchMode) };
   }
 

package/src/server/lib/omp/session/todos.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Read one session's todo state from its transcript.
+ *
+ * The list is omp's, and its only durable home is the session JSONL — there is
+ * no separate todo file and no chamber-side copy to fall out of date. So the
+ * read is: locate the session file, parse it, and take the deepest committed
+ * snapshot on the active branch (`latestTodoSnapshot`).
+ *
+ * Two properties of this read are deliberate:
+ *
+ *   - **It is a full-file parse, cached by size+mtime.** Measured on real
+ *     sessions (7.2 MB / 1905 entries) a full parse is ~15 ms, and the todos
+ *     may sit megabytes from EOF — a `todo` call near the start of a long
+ *     session stays the live list for the rest of it, so a bounded tail window
+ *     would report "no todos" for exactly the sessions that have the most. omp
+ *     flushes each entry as it appends, so a poll sees a new list within the
+ *     second it was written.
+ *   - **It never creates an omp process.** The session is read-only here; a
+ *     panel that spawned a child per poll would fight the chat's own session
+ *     wrapper for the same session file.
+ */
+
+import { findSessionFileById } from '@/server/lib/omp/session/locator';
+import { parseJsonlLenient } from '@/shared/lib/omp/session/jsonl';
+import { latestTodoSnapshot, todoProgress } from '@/shared/lib/chat/todo/snapshot';
+import type { SessionTodoState } from '@/shared/types/todo';
+
+/** Sessions larger than this are refused rather than parsed; a transcript past
+ *  it is pathological, and the read runs behind an HTTP request. */
+const MAX_TODO_SESSION_BYTES = 512 * 1024 * 1024;
+
+interface TodoCacheEntry {
+  size: number;
+  mtimeMs: number;
+  state: SessionTodoState;
+}
+
+/**
+ * Cache keyed by session id. Hangs off `globalThis` for the same reason the
+ * session-file caches do: a `bun --hot` reload re-evaluates modules but keeps
+ * `globalThis`, and a cache that vanished on every edit would re-parse a
+ * multi-megabyte file per poll during development.
+ */
+interface TodoCacheHost {
+  entries: Map<string, TodoCacheEntry>;
+}
+
+declare global {
+  // eslint-disable-next-line no-var
+  var __ompChamberTodoCache: TodoCacheHost | undefined;
+}
+
+function cache(): TodoCacheHost {
+  globalThis.__ompChamberTodoCache ??= { entries: new Map() };
+  return globalThis.__ompChamberTodoCache;
+}
+
+const EMPTY_TODO_STATE: SessionTodoState = { snapshot: null, progress: todoProgress([]) };
+
+/**
+ * The todo state of one session. Returns an empty state (never a throw) when
+ * the transcript cannot be read: a session whose file is gone is a normal
+ * condition for a sidebar entry the user has not opened yet, and the panel
+ * reports "no todos" rather than an error for it.
+ */
+export async function readSessionTodos(sessionId: string): Promise<SessionTodoState> {
+  const filePath = await findSessionFileById(sessionId);
+  if (!filePath) return EMPTY_TODO_STATE;
+
+  let size: number;
+  let mtimeMs: number;
+  try {
+    const stats = await Bun.file(filePath).stat();
+    if (stats.size > MAX_TODO_SESSION_BYTES) return EMPTY_TODO_STATE;
+    size = stats.size;
+    mtimeMs = stats.mtimeMs;
+  } catch {
+    return EMPTY_TODO_STATE;
+  }
+
+  const slot = cache().entries.get(sessionId);
+  if (slot && slot.size === size && slot.mtimeMs === mtimeMs) return slot.state;
+
+  let body: string;
+  try {
+    body = await Bun.file(filePath).text();
+  } catch {
+    return EMPTY_TODO_STATE;
+  }
+
+  const snapshot = latestTodoSnapshot(parseJsonlLenient<Record<string, unknown>>(body));
+  const state: SessionTodoState = { snapshot, progress: todoProgress(snapshot?.phases ?? []) };
+  cache().entries.set(sessionId, { size, mtimeMs, state });
+  return state;
+}

package/src/server/routes/fs/action-create.test.ts

@@ -0,0 +1,90 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Files panel's "New file" branch.
+ *
+ * Two rules are load-bearing and neither is visible from the happy path: the
+ * name may not carry a path separator (the folder is named by `path`, and a
+ * separator would turn a name into an arbitrary write under the root), and an
+ * existing file is REFUSED rather than truncated. The second one is the one a
+ * naive `Bun.write` gets wrong: `Bun.write` creates or truncates, so a name
+ * that collides with a real file would silently blank it.
+ */
+
+import { afterEach, describe, expect, test } from 'bun:test';
+import fs from 'fs';
+import path from 'path';
+import { action } from '@/server/routes/fs/action';
+
+/** Probes live in the repo root — the one directory the root allow-list always accepts. */
+const DIR = path.join(process.cwd(), 'tmp-create-probe');
+const NESTED = path.join(DIR, 'sub');
+
+afterEach(() => {
+  fs.rmSync(DIR, { recursive: true, force: true });
+});
+
+async function create(folderPath: string, name: string) {
+  const form = new FormData();
+  form.append('actionType', 'create');
+  form.append('root', process.cwd());
+  form.append('path', folderPath);
+  form.append('name', name);
+  const res = await action({ request: new Request('http://localhost/api/fs/action', { method: 'POST', body: form }) } as never);
+  return { status: res.status, body: (await res.json()) as { success?: boolean; path?: string; error?: string } };
+}
+
+describe('fs create', () => {
+  test('creates an empty file in the named folder and reports its relative path', async () => {
+    fs.mkdirSync(DIR, { recursive: true });
+    const { status, body } = await create('tmp-create-probe', 'notes.md');
+
+    expect(status).toBe(200);
+    expect(body).toEqual({ success: true, path: 'tmp-create-probe/notes.md' });
+    expect(fs.readFileSync(path.join(DIR, 'notes.md'), 'utf8')).toBe('');
+  });
+
+  test('creates inside a nested folder path, which is how a subfolder is targeted', async () => {
+    fs.mkdirSync(NESTED, { recursive: true });
+    const { status, body } = await create('tmp-create-probe/sub', 'index.ts');
+
+    expect(status).toBe(200);
+    expect(body.path).toBe('tmp-create-probe/sub/index.ts');
+    expect(fs.existsSync(path.join(NESTED, 'index.ts'))).toBe(true);
+  });
+
+  test('refuses an existing name instead of truncating it', async () => {
+    fs.mkdirSync(DIR, { recursive: true });
+    fs.writeFileSync(path.join(DIR, 'keep.txt'), 'important');
+
+    const { status, body } = await create('tmp-create-probe', 'keep.txt');
+
+    expect(status).toBe(409);
+    expect(body.error).toContain('already exists');
+    expect(fs.readFileSync(path.join(DIR, 'keep.txt'), 'utf8')).toBe('important');
+  });
+
+  test('refuses a name carrying a path separator', async () => {
+    fs.mkdirSync(DIR, { recursive: true });
+    for (const name of ['../escape.txt', 'sub/escape.txt', 'sub\\escape.txt']) {
+      const { status } = await create('tmp-create-probe', name);
+      expect(status).toBe(400);
+    }
+    expect(fs.existsSync(path.join(process.cwd(), 'escape.txt'))).toBe(false);
+  });
+
+  test('refuses an empty or whitespace-only name', async () => {
+    fs.mkdirSync(DIR, { recursive: true });
+    expect((await create('tmp-create-probe', '   ')).status).toBe(400);
+    expect((await create('tmp-create-probe', '.')).status).toBe(400);
+    expect((await create('tmp-create-probe', '..')).status).toBe(400);
+  });
+
+  test('refuses a folder that resolves outside the root', async () => {
+    const { status } = await create('../outside', 'x.txt');
+    expect(status).toBe(403);
+  });
+});

package/src/server/routes/fs/action.ts

@@ -37,6 +37,29 @@ export async function action({ request }: ActionFunctionArgs) {
       await fs.promises.mkdir(path.dirname(fullPath), { recursive: true });
       await Bun.write(fullPath, content);
       return json({ success: true });
+    } else if (actionType === 'create') {
+      // The Files panel's "New file": an empty file beside the folder that was
+      // right-clicked. Only a NAME is accepted, never a path — a separator
+      // would let the panel write anywhere under the root, and the folder is
+      // already named by `path`.
+      const name = ((formData.get('name') as string) ?? '').trim();
+      if (!name || name === '.' || name === '..' || /[/\\\0]/.test(name)) {
+        return json({ error: 'Enter a file name without slashes' }, { status: 400 });
+      }
+      const target = resolveWithinRoot(scopedRoot, path.join(filePath || '.', name));
+      if (!target) {
+        return json({ error: 'Invalid path' }, { status: 403 });
+      }
+      // Creating must never overwrite: a name that already exists is reported,
+      // not truncated — the panel offers Rename for that, and an empty write
+      // here would destroy the file the user meant to keep.
+      if ((await Bun.file(target).stat().catch(() => null)) !== null) {
+        return json({ error: `${name} already exists` }, { status: 409 });
+      }
+      await fs.promises.mkdir(path.dirname(target), { recursive: true });
+      await Bun.write(target, '');
+      // Relative to the LISTED root, which is the identity the tree renders by.
+      return json({ success: true, path: path.relative(scopedRoot, target).split(path.sep).join('/') });
     } else if (actionType === 'delete') {
       await fs.promises.rm(fullPath, { recursive: true, force: true });
       return json({ success: true });

package/src/server/routes/omp/index.ts

@@ -2,6 +2,7 @@ import { bindingsFor, type HandlerBinding } from '@/server/lib/route-adapter';
 import * as ompState from '@/server/routes/omp/state';
 import * as ompSidebar from '@/server/routes/omp/sidebar';
 import * as ompSessionStats from '@/server/routes/omp/session-stats';
+import * as ompSessionTodos from '@/server/routes/omp/session-todos';
 import * as ompCommands from '@/server/routes/omp/commands';
 import * as ompExtensions from '@/server/routes/omp/extensions';
 import * as ompLogin from '@/server/routes/omp/login';
@@ -12,6 +13,7 @@ export const ompBindings: HandlerBinding[] = [
   ...bindingsFor(ompState, '/api/omp/state'),
   ...bindingsFor(ompSidebar, '/api/omp/sidebar'),
   ...bindingsFor(ompSessionStats, '/api/omp/session-stats'),
+  ...bindingsFor(ompSessionTodos, '/api/omp/session-todos'),
   ...bindingsFor(ompCommands, '/api/omp/commands'),
   ...bindingsFor(ompExtensions, '/api/omp/extensions'),
   ...bindingsFor(ompLogin, '/api/omp/login'),

package/src/server/routes/omp/session-todos.ts

@@ -0,0 +1,80 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * GET /api/omp/session-todos?sessionId=<uuid> — the session's live todo list.
+ *
+ * Read-only projection of oh-my-pi's own persisted `todo` state: the deepest
+ * committed snapshot on the session transcript's active branch. omp is the
+ * owner of this list and there is no second copy — see
+ * `@/server/lib/omp/session/todos`.
+ *
+ * MOCK mode answers a deterministic demo list so the right-panel view renders
+ * its full range of states (in progress, blocked, completed, abandoned) without
+ * an omp install.
+ */
+
+import { json, NO_STORE_HEADERS } from '@/server/lib/remix-compat';
+import type { LoaderFunctionArgs } from '@/server/lib/remix-compat';
+import { isMockMode } from '@/server/mock.server';
+import { readSessionTodos } from '@/server/lib/omp/session/todos';
+import { todoProgress } from '@/shared/lib/chat/todo/snapshot';
+import type { SessionTodosPayload, TodoPhase } from '@/shared/types/todo';
+
+/** Demo list under MOCK=true: one phase of every status the panel must draw. */
+const MOCK_PHASES: TodoPhase[] = [
+  {
+    name: 'Server data',
+    tasks: [
+      { content: 'Read the session transcript for the deepest todo snapshot', status: 'completed' },
+      { content: 'Serve the list over /api/omp/session-todos', status: 'in_progress' },
+      { content: 'Cache the parse by size + mtime', status: 'pending' },
+      { content: 'Wire the panel poll to omp:session-updated', status: 'blocked', blocker: 'waiting on the event name' },
+    ],
+  },
+  {
+    name: 'Panel',
+    tasks: [
+      { content: 'Draw phase groups with per-status glyphs', status: 'pending' },
+      { content: 'Collapse closed tasks behind a toggle', status: 'abandoned' },
+    ],
+  },
+];
+
+export async function loader({ request }: LoaderFunctionArgs) {
+  const url = new URL(request.url);
+  const sessionId = url.searchParams.get('sessionId');
+
+  if (isMockMode()) {
+    return json(
+      {
+        sessionId: sessionId ?? 'mock',
+        snapshot: {
+          phases: MOCK_PHASES,
+          sourceEntryId: 'mock-entry',
+          source: 'toolResult',
+          updatedAt: new Date().toISOString(),
+          op: 'start',
+          storage: 'session',
+        },
+        progress: todoProgress(MOCK_PHASES),
+        generatedAt: new Date().toISOString(),
+        isMock: true,
+      } satisfies SessionTodosPayload,
+      { headers: NO_STORE_HEADERS },
+    );
+  }
+
+  if (!sessionId) return json({ error: 'sessionId is required' }, { status: 400 });
+
+  const state = await readSessionTodos(sessionId);
+  const payload: SessionTodosPayload = {
+    sessionId,
+    ...state,
+    generatedAt: new Date().toISOString(),
+    isMock: false,
+  };
+  return json(payload, { headers: NO_STORE_HEADERS });
+}

package/src/shared/lib/chat/{todo-parser.ts → todo/parser.ts}

@@ -1,3 +1,20 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Renderer-side parser for one `todo` tool call: reads the human-readable
+ * checklist omp returns as the tool's text output (and the `list` argument as a
+ * fallback) into phase groups for the chat timeline's tool card.
+ *
+ * This is NOT the authoritative list — a tool card shows what that ONE call
+ * did, while the session's live list is the deepest committed snapshot on the
+ * active branch (`./snapshot.ts`, surfaced by the right-panel Todo view). The
+ * two must not be merged: a card that displayed the session-wide list would
+ * attribute every other call's work to this one.
+ */
+
 import type { ToolCallData } from '@/shared/types';
 
 export interface ParsedTask {