fix(dream): deterministic last-writer attribution for colliding slugs

collectChildPutPageSlugs paired each slug to a jobId first-seen over an
unordered result set. When two children collide on a final slug, the pages
row holds the LAST put_page write, so the provenance stamp
(transcript_id/transcript_source/date) could attribute an arbitrary other
transcript. ORDER BY id + last-writer-wins aligns the stamp with the
surviving content; pinned by a collision test.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/tutorials/company-brain.md

@@ -223,16 +223,14 @@ export GBRAIN_REMOTE_CLIENT_ID=<Alice's client_id>
 export GBRAIN_REMOTE_CLIENT_SECRET=<Alice's client_secret>
 export GBRAIN_REMOTE_MCP_URL=https://brain.acme-co.com/mcp
 
-gbrain search "performance review"
+gbrain search "performance review" --remote
 ```
 
-(On a thin-client install every shared op routes through the remote MCP server automatically — no flag needed. The env vars select whose credentials the call uses.)
-
 Alice should see results only from `customers` and `shared`. The performance-review notes live in `internal`, which she's not scoped to read. She shouldn't see them.
 
 ```bash
 # Terminal 2, as Bob (export his credentials similarly)
-gbrain search "performance review"
+gbrain search "performance review" --remote
 ```
 
 Bob should see the performance-review notes from `internal`, plus anything related from `shared`. He shouldn't see anything that lives only in `customers`.
@@ -516,7 +514,7 @@ The first sync embeds every page, which takes time. Check `gbrain sources status
 
 ### "I see a page I shouldn't see"
 
-This shouldn't happen, but if you suspect it, run `gbrain search <query> --json` as the constrained client (thin-client install, with the client's `GBRAIN_REMOTE_*` env exported) and inspect the `source_id` field on every returned result. Every row should be in the client's `--federated-read` set. If one isn't, file an issue with the exact slug and source IDs.
+This shouldn't happen, but if you suspect it, run `gbrain search <query> --remote --json` as the constrained client and inspect the `source_id` field on every returned result. Every row should be in the client's `--federated-read` set. If one isn't, file an issue with the exact slug and source IDs.
 
 ### "The synthesized answer is wrong"
 

src/cli.ts

@@ -464,11 +464,7 @@ async function main() {
     // routed path. Date → ISO string; bigint → string (postgres.js shape);
     // Buffer → object. Microsecond-cost; eliminates a whole drift bug class.
     const result = JSON.parse(JSON.stringify(rawResult, bigintToStringReplacer));
-    // #380 pass-through: `--json` (undeclared on most ops, promised by docs)
-    // emits the raw op result instead of the human formatter.
-    const output = params.json === true
-      ? JSON.stringify(result, null, 2) + '\n'
-      : formatResult(op.name, result);
+    const output = formatResult(op.name, result);
     if (output) process.stdout.write(output);
   } catch (e: unknown) {
     // v0.42.20.0 (codex D4): on error, set exitCode + return so the `finally`
@@ -551,10 +547,7 @@ async function runThinClientRouted(
       signal: sigintController.signal,
     });
     const result = unpackToolResult(raw);
-    // #380: same --json seam as the local-engine path (renderer parity).
-    const output = params.json === true
-      ? JSON.stringify(result, null, 2) + '\n'
-      : formatResult(op.name, result);
+    const output = formatResult(op.name, result);
     if (output) process.stdout.write(output);
   } catch (e: unknown) {
     if (e instanceof RemoteMcpError) {
@@ -764,28 +757,10 @@ export function resolveQueryImage(
   return { path: imagePath, base64, mime };
 }
 
-/**
- * #380: undeclared flags that are honored DOWNSTREAM of parseOpArgs and must
- * keep passing through when unknown flags become hard errors:
- *   - source     → makeContext's resolveSourceId (the --source axis)
- *   - brain      → the mount/brain routing axis (docs promise the flag)
- *   - dry_run    → makeContext's ctx.dryRun (ops without a declared dry_run)
- *   - json       → raw-JSON output seam (local + thin-client paths)
- */
-const PASSTHROUGH_VALUE_FLAGS = new Set(['source', 'brain']);
-const PASSTHROUGH_BOOL_FLAGS = new Set(['dry_run', 'json']);
-
 export function parseOpArgs(op: Operation, args: string[]): Record<string, unknown> {
   const params: Record<string, unknown> = {};
   const positional = op.cliHints?.positional || [];
   let posIdx = 0;
-  const cliName = op.cliHints?.name || op.name;
-  const MAX_STDIN = 5_000_000; // 5MB cap, shared by stdin and --file
-  // #380: `--file <path>` fills the op's declared stdin param (put's `content`)
-  // from a file. Driven by cliHints.stdin — no per-op hard-coding — and
-  // disabled when the op declares a real `file` param of its own.
-  const fileParam = op.cliHints?.stdin && !op.params.file ? op.cliHints.stdin : undefined;
-  let filePath: string | undefined;
 
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -799,42 +774,12 @@ export function parseOpArgs(op: Operation, args: string[]): Record<string, unkno
         }
       }
       const key = arg.slice(2).replace(/-/g, '_');
-      if (fileParam && key === 'file') {
-        if (i + 1 >= args.length) {
-          console.error(`Error: ${arg} requires a value.`);
-          process.exit(1);
-        }
-        filePath = args[++i];
-        continue;
-      }
       const paramDef = op.params[key];
-      if (!paramDef) {
-        if (PASSTHROUGH_BOOL_FLAGS.has(key)) {
-          params[key] = true;
-          continue;
-        }
-        if (PASSTHROUGH_VALUE_FLAGS.has(key)) {
-          if (i + 1 >= args.length) {
-            console.error(`Error: ${arg} requires a value.`);
-            process.exit(1);
-          }
-          params[key] = args[++i];
-          continue;
-        }
-        // #380: unknown flags were silently swallowed into params, so typos
-        // like `put --file` created empty pages instead of erroring.
-        console.error(`Unknown option for gbrain ${cliName}: ${arg}`);
-        console.error(`Run 'gbrain ${cliName} --help' for valid flags.`);
-        process.exit(1);
-      }
-      if (paramDef.type === 'boolean') {
+      if (paramDef?.type === 'boolean') {
         params[key] = true;
       } else if (i + 1 < args.length) {
         params[key] = args[++i];
-        if (paramDef.type === 'number') params[key] = Number(params[key]);
-      } else {
-        console.error(`Error: ${arg} requires a value.`);
-        process.exit(1);
+        if (paramDef?.type === 'number') params[key] = Number(params[key]);
       }
     } else if (posIdx < positional.length) {
       const key = positional[posIdx++];
@@ -843,30 +788,10 @@ export function parseOpArgs(op: Operation, args: string[]): Record<string, unkno
     }
   }
 
-  // #380: resolve --file AFTER the loop so --file/--content conflicts are
-  // caught in either order.
-  if (filePath !== undefined && fileParam) {
-    if (params[fileParam] !== undefined) {
-      console.error(`Error: use only one of --file, --${fileParam}, or stdin for gbrain ${cliName}.`);
-      process.exit(1);
-    }
-    let fileContent: string;
-    try {
-      fileContent = readFileSync(filePath, 'utf-8');
-    } catch (e) {
-      console.error(`Error: cannot read --file ${filePath}: ${e instanceof Error ? e.message : String(e)}`);
-      process.exit(1);
-    }
-    if (Buffer.byteLength(fileContent, 'utf-8') > MAX_STDIN) {
-      console.error(`Error: file content exceeds ${MAX_STDIN} bytes. Split into smaller inputs.`);
-      process.exit(1);
-    }
-    params[fileParam] = fileContent;
-  }
-
   // Read stdin for content params
   if (op.cliHints?.stdin && !params[op.cliHints.stdin] && !process.stdin.isTTY) {
     const stdinContent = readFileSync(0, 'utf-8');
+    const MAX_STDIN = 5_000_000; // 5MB
     if (Buffer.byteLength(stdinContent, 'utf-8') > MAX_STDIN) {
       console.error(`Error: stdin content exceeds ${MAX_STDIN} bytes. Split into smaller inputs.`);
       process.exit(1);
@@ -2328,10 +2253,6 @@ export function printOpHelp(op: Operation, invokedName?: string) {
       const prefix = isPos ? `  <${key}>` : `  --${key.replace(/_/g, '-')}`;
       console.log(`${prefix.padEnd(28)} ${def.description || ''}${req}`);
     }
-    // #380: ops that read stdin also accept --file <path> (parseOpArgs).
-    if (op.cliHints?.stdin && !op.params.file) {
-      console.log(`${'  --file <path>'.padEnd(28)} Read ${op.cliHints.stdin} from a file (alternative to --${op.cliHints.stdin} or stdin)`);
-    }
   }
 }
 

src/core/cycle/synthesize.ts

@@ -428,8 +428,13 @@ export async function runPhaseSynthesize(
 
     const queue = new MinionQueue(engine);
     const childIds: number[] = [];
-    /** Map child job_id → chunk metadata for D6 orchestrator-side slug rewrite. */
-    const chunkInfo = new Map<number, { idx: number; hash6: string }>();
+    /**
+     * Map child job_id → transcript metadata. Drives D6 orchestrator-side
+     * slug rewrite for chunked transcripts AND the deterministic frontmatter
+     * stampDreamProvenance merges into each written page. Populated for
+     * every child (single-chunk children carry chunkTotal=1).
+     */
+    const childMeta = new Map<number, ChildMeta>();
     /** Skip reasons for the cycle report (D5 cap hits, D8 legacy-key skips). */
     const skipReports: Array<{ filePath: string; reason: string }> = [];
 
@@ -513,9 +518,14 @@ export async function runPhaseSynthesize(
           { allowProtectedSubmit: true },
         );
         childIds.push(child.id);
-        if (isChunked) {
-          chunkInfo.set(child.id, { idx: i, hash6 });
-        }
+        childMeta.set(child.id, {
+          idx: i,
+          hash6,
+          chunkTotal: chunks.length,
+          transcriptSource: t.transcriptSource,
+          transcriptId: stripContentVersionSuffix(t.basename),
+          inferredDate: t.inferredDate,
+        });
       }
     }
 
@@ -544,14 +554,14 @@ export async function runPhaseSynthesize(
 
     // Collect slugs from put_page tool executions across the children
     // (codex finding #2: deterministic provenance, NOT pages.updated_at).
-    // D6 orchestrator slug rewrite: chunkInfo drives post-hoc rewrite of
+    // D6 orchestrator slug rewrite: childMeta drives post-hoc rewrite of
     // bare-hash slugs to `<hash6>-c<idx>` so chunked siblings can't collide
     // even if Sonnet drops the chunk suffix.
     // v0.32.8: refs carry source_id so reverseWriteRefs picks the correct
     // (source, slug) row. #1586: refs are stamped with the cycle's resolved
     // source (children write there via SubagentHandlerData.source_id).
     const cycleSourceId = opts.sourceId ?? 'default';
-    const writtenRefs = await collectChildPutPageSlugs(engine, childIds, chunkInfo, cycleSourceId);
+    const writtenRefs = await collectChildPutPageSlugs(engine, childIds, childMeta, cycleSourceId);
 
     const summaryDate = opts.date ?? today();
 
@@ -559,7 +569,12 @@ export async function runPhaseSynthesize(
     // of every child-written page BEFORE reverse-rendering, so generated pages
     // are queryable (`frontmatter->>'dream_generated'`) and a later put_page
     // write-through (which re-renders from the DB row) can't erase the stamp.
-    await stampDreamProvenance(engine, writtenRefs, summaryDate);
+    // #2285: the stamp also carries the orchestrator-owned deterministic
+    // frontmatter (transcript_id, transcript_source, transcript_hash, date,
+    // chunk) derived from childMeta — subagent drift on those fields can't
+    // leak, and reverseWriteRefs below re-reads the row so the same fields
+    // land in the on-disk markdown.
+    await stampDreamProvenance(engine, writtenRefs, summaryDate, childMeta);
 
     // Dual-write: reverse-render each DB row → markdown file.
     const reverseWriteCount = await reverseWriteRefs(engine, opts.brainDir, writtenRefs, cycleSourceId);
@@ -1095,15 +1110,17 @@ function sanitizeForSlug(s: string): string {
  * fake"): we no longer need detection because the rewrite enforces
  * uniqueness at slug-write time.
  *
- * `chunkInfo` maps child job_id → { chunk_index, hash6 }. Single-chunk
- * children are absent from the map and pass through unchanged.
+ * `childMeta` maps child job_id → per-child transcript metadata. Chunked
+ * children (chunkTotal > 1) get the slug rewrite; single-chunk children
+ * pass through unchanged. Each returned ref carries the job_id that wrote
+ * it so stampDreamProvenance can pair the slug back to its childMeta entry.
  */
 async function collectChildPutPageSlugs(
   engine: BrainEngine,
   childIds: number[],
-  chunkInfo: Map<number, { idx: number; hash6: string }>,
+  childMeta: Map<number, ChildMeta>,
   sourceId = 'default',
-): Promise<Array<{ slug: string; source_id: string }>> {
+): Promise<Array<{ slug: string; source_id: string; jobId: number }>> {
   if (childIds.length === 0) return [];
   // Raw fetch — NO SELECT DISTINCT. Preserves per-child slug duplicates so
   // the orchestrator sees what each child wrote. COALESCE handles both
@@ -1122,16 +1139,73 @@ async function collectChildPutPageSlugs(
        FROM subagent_tool_executions
       WHERE job_id = ANY($1::int[])
         AND tool_name = 'brain_put_page'
-        AND status = 'complete'`,
+        AND status = 'complete'
+      ORDER BY id`,
     [childIds],
   );
-  const rewritten = new Set<string>();
+  const rewritten = new Map<string, number>();
   for (const r of rows) {
     if (typeof r.slug !== 'string' || r.slug.length === 0) continue;
-    const ci = chunkInfo.get(r.job_id);
-    rewritten.add(ci ? rewriteChunkedSlug(r.slug, ci.hash6, ci.idx) : r.slug);
+    const meta = childMeta.get(r.job_id);
+    const finalSlug = meta && meta.chunkTotal > 1
+      ? rewriteChunkedSlug(r.slug, meta.hash6, meta.idx)
+      : r.slug;
+    // Last writer wins, in execution-row order (ORDER BY id): if two children
+    // collide on a final slug, the pages row holds the LAST put_page write, so
+    // the stamp must attribute that child's transcript — not an arbitrary one.
+    rewritten.set(finalSlug, r.job_id);
   }
-  return Array.from(rewritten).sort().map(slug => ({ slug, source_id: sourceId }));
+  return [...rewritten.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([slug, jobId]) => ({ slug, source_id: sourceId, jobId }));
+}
+
+/**
+ * Per-child orchestrator state. Drives D6 chunked-slug rewrite (idx + hash6)
+ * AND the deterministic frontmatter stampDreamProvenance merges into each
+ * written page. Populated for every child, not just chunked ones.
+ */
+interface ChildMeta {
+  idx: number;
+  hash6: string;
+  chunkTotal: number;
+  transcriptSource: string | null;
+  transcriptId: string;
+  inferredDate: string | null;
+}
+
+/**
+ * Strip the content-version suffix that claude-code-archive appends when a
+ * conversation is edited (`<uuid>--<contentHash>.md`). The session UUID is
+ * the stable transcript identifier; the suffix changes with content. Used to
+ * populate `transcript_id` so edits of the same session collapse to one id.
+ */
+function stripContentVersionSuffix(basename: string): string {
+  return basename.replace(/--[a-f0-9]+$/i, '');
+}
+
+/**
+ * Deterministic frontmatter for one synthesized page (#2285). Every field
+ * here is owned by the orchestrator — the subagent's value for any of these
+ * is overwritten. The subagent retains authority over type / title / tags /
+ * body. `date` feeds the effective-date precedence chain
+ * (src/core/effective-date.ts) so re-imports keep the conversation date even
+ * when sync tools re-stamp file mtimes.
+ */
+function buildDeterministicFrontmatter(
+  meta: ChildMeta,
+  cycleDate: string,
+): Record<string, unknown> {
+  const overrides: Record<string, unknown> = {
+    dream_generated: true,
+    dream_cycle_date: cycleDate,
+    transcript_id: meta.transcriptId,
+    transcript_hash: meta.hash6,
+  };
+  if (meta.transcriptSource) overrides.transcript_source = meta.transcriptSource;
+  if (meta.chunkTotal > 1) overrides.chunk = `${meta.idx + 1}/${meta.chunkTotal}`;
+  if (meta.inferredDate) overrides.date = meta.inferredDate;
+  return overrides;
 }
 
 /**
@@ -1177,12 +1251,19 @@ async function hasLegacySingleChunkCompletion(
  */
 async function stampDreamProvenance(
   engine: BrainEngine,
-  refs: Array<{ slug: string; source_id: string }>,
+  refs: Array<{ slug: string; source_id: string; jobId?: number }>,
   cycleDate: string,
+  childMeta?: Map<number, ChildMeta>,
 ): Promise<void> {
   if (refs.length === 0) return;
   const { executeRawJsonb } = await import('../sql-query.ts');
-  for (const { slug, source_id } of refs) {
+  for (const { slug, source_id, jobId } of refs) {
+    // #2285: when the ref pairs back to a child, the stamp also carries the
+    // orchestrator-owned deterministic frontmatter for that transcript.
+    const meta = jobId !== undefined ? childMeta?.get(jobId) : undefined;
+    const stamp = meta
+      ? buildDeterministicFrontmatter(meta, cycleDate)
+      : { dream_generated: true, dream_cycle_date: cycleDate };
     try {
       await executeRawJsonb(
         engine,
@@ -1190,7 +1271,7 @@ async function stampDreamProvenance(
             SET frontmatter = COALESCE(frontmatter, '{}'::jsonb) || $3::jsonb
           WHERE slug = $1 AND source_id = $2`,
         [slug, source_id],
-        [{ dream_generated: true, dream_cycle_date: cycleDate }],
+        [stamp],
       );
     } catch (e) {
       const msg = e instanceof Error ? e.message : String(e);

src/core/cycle/transcript-discovery.ts

@@ -10,7 +10,7 @@
  */
 
 import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { join, basename } from 'node:path';
+import { join, basename, dirname } from 'node:path';
 import { createHash } from 'node:crypto';
 import { pruneDir } from '../sync.ts';
 
@@ -23,8 +23,22 @@ export interface DiscoveredTranscript {
   content: string;
   /** Filename basename without extension; used as a topic-slug seed. */
   basename: string;
-  /** Inferred date if the basename matches `YYYY-MM-DD...` (or null). */
+  /**
+   * Inferred conversation date (YYYY-MM-DD) or null. Precedence: the
+   * `| First message | <ISO> |` row in the transcript's `## Metadata`
+   * table (stable across mtime-restamping re-syncs) wins; a leading
+   * `YYYY-MM-DD` in the basename is the fallback.
+   */
   inferredDate: string | null;
+  /**
+   * Transcript source archive name, derived from the path's grandparent
+   * directory (the immediate parent of the date directory). For the
+   * canonical layout `<corpus>/<source>/<date>/<id>.md` this yields the
+   * source-name segment — e.g. `claude-code` for the claude-code-archive
+   * output, `meetings` for meeting recordings. Null when the file does
+   * not live under a `<source>/<date>/` pair (ad-hoc inputs).
+   */
+  transcriptSource: string | null;
 }
 
 export interface DiscoverOpts {
@@ -161,6 +175,36 @@ function matchesAnyExclude(text: string, patterns: RegExp[]): boolean {
   return false;
 }
 
+/**
+ * Content-based conversation date: the `| First message | <ISO timestamp> |`
+ * row claude-code-archive writes into the transcript's `## Metadata` table.
+ * Stable across rsync/Dropbox/Syncthing/B2 re-syncs that re-stamp mtime,
+ * unlike anything derived from file metadata. Returns YYYY-MM-DD or null.
+ */
+const FIRST_MESSAGE_RE = /^\|\s*First message\s*\|\s*(\d{4}-\d{2}-\d{2})/im;
+
+export function inferContentDate(content: string): string | null {
+  const m = FIRST_MESSAGE_RE.exec(content);
+  return m ? m[1] : null;
+}
+
+/**
+ * Derive the archive source name from a transcript path. Returns the basename
+ * of the directory two levels above the file when the immediate parent is a
+ * date directory and the grandparent looks like a source-name slug (lowercase
+ * alphanumeric segments separated by hyphens); otherwise null. This pins the
+ * canonical claude-code-archive layout `<corpus>/<source>/<date>/<id>.md`
+ * without claiming a source for ad-hoc inputs that don't match.
+ */
+export function deriveTranscriptSource(filePath: string): string | null {
+  const parentName = basename(dirname(filePath));
+  if (!/^\d{4}-\d{2}-\d{2}/.test(parentName)) return null;
+  const grandparentName = basename(dirname(dirname(filePath)));
+  if (!grandparentName) return null;
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(grandparentName)) return null;
+  return grandparentName;
+}
+
 function listTextFiles(dir: string): string[] {
   // Recursive walk with descent-time pruning (closes codex C12/C13 spec gap).
   // Accepts BOTH .txt and .md per transcript-discovery's domain rules — does
@@ -225,8 +269,11 @@ export function discoverTranscripts(opts: DiscoverOpts): DiscoveredTranscript[]
       const ext = filePath.endsWith('.md') ? '.md' : '.txt';
       const baseName = basename(filePath, ext);
       const dateMatch = DATE_RE.exec(baseName);
-      const inferredDate = dateMatch ? dateMatch[1] : null;
-      if (!isInDateRange(inferredDate, opts)) continue;
+      const filenameDate = dateMatch ? dateMatch[1] : null;
+      // Fast path: date-named files outside the window skip before the read.
+      // ponytail: a date-named file whose content date differs is filtered on
+      // its filename date — acceptable; archive layouts use UUID basenames.
+      if (filenameDate && !isInDateRange(filenameDate, opts)) continue;
 
       let content: string;
       try {
@@ -241,12 +288,17 @@ export function discoverTranscripts(opts: DiscoverOpts): DiscoveredTranscript[]
       }
       if (matchesAnyExclude(content, excludeRes)) continue;
 
+      // Content-metadata date wins (survives mtime restamps); filename next.
+      const inferredDate = inferContentDate(content) ?? filenameDate;
+      if (!isInDateRange(inferredDate, opts)) continue;
+
       results.push({
         filePath,
         contentHash: hashContent(content),
         content,
         basename: baseName,
         inferredDate,
+        transcriptSource: deriveTranscriptSource(filePath),
       });
     }
   }
@@ -290,6 +342,7 @@ export function readSingleTranscript(
     contentHash: hashContent(content),
     content,
     basename: baseName,
-    inferredDate: dateMatch ? dateMatch[1] : null,
+    inferredDate: inferContentDate(content) ?? (dateMatch ? dateMatch[1] : null),
+    transcriptSource: deriveTranscriptSource(filePath),
   };
 }

src/core/operations.ts

@@ -769,7 +769,7 @@ const get_page: Operation = {
 
 const put_page: Operation = {
   name: 'put_page',
-  description: 'Write/update a page (markdown with frontmatter). Chunks, embeds, reconciles tags, and (when auto_link/auto_timeline are enabled) extracts + reconciles graph links and timeline entries. On the CLI, `gbrain put SLUG --file PATH` reads content from a file (also `--content` or stdin). For provenance write-through and a binary-NUL guard, prefer `gbrain capture --file PATH --slug SLUG` (v0.39.3.0).',
+  description: 'Write/update a page (markdown with frontmatter). Chunks, embeds, reconciles tags, and (when auto_link/auto_timeline are enabled) extracts + reconciles graph links and timeline entries. For large content on Windows (pipe-buffer limit ~45KB) or any file-as-input workflow, use `gbrain capture --file PATH --slug SLUG` — capture reads the file as a Buffer with a binary-NUL guard and adds provenance write-through (v0.39.3.0).',
   params: {
     slug: { type: 'string', required: true, description: 'Page slug' },
     content: { type: 'string', required: true, description: 'Full markdown content with YAML frontmatter' },
@@ -1384,10 +1384,7 @@ const list_pages: Operation = {
   params: {
     type: { type: 'string', description: 'Filter by page type' },
     tag: { type: 'string', description: 'Filter by tag' },
-    limit: { type: 'number', description: 'Max results (default 50, capped at 100 — use offset to paginate beyond)' },
-    // #2876: the 100-row cap was silent and there was no way past it even
-    // though both engines already support OFFSET on listPages.
-    offset: { type: 'number', description: 'Skip first N results (pagination; pair with limit)' },
+    limit: { type: 'number', description: 'Max results (default 50)' },
     // v0.29 — surface filter that already exists on PageFilters.
     updated_after: {
       type: 'string',
@@ -1418,10 +1415,6 @@ const list_pages: Operation = {
       type: p.type as any,
       tag: p.tag as string,
       limit: clampSearchLimit(p.limit as number | undefined, 50, 100),
-      // #2876: thread pagination through (engines already honor offset).
-      offset: Number.isFinite(p.offset as number) && (p.offset as number) > 0
-        ? Math.floor(p.offset as number)
-        : undefined,
       includeDeleted: (p.include_deleted as boolean) === true,
       updated_after: typeof p.updated_after === 'string' ? p.updated_after : undefined,
       sort,

test/cli-args.test.ts

@@ -1,41 +1,8 @@
 import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, rmSync, writeFileSync } from 'fs';
-import { tmpdir } from 'os';
-import { join } from 'path';
 import { parseOpArgs } from '../src/cli.ts';
 import { operationsByName } from '../src/core/operations.ts';
 
 describe('parseOpArgs', () => {
-  // #380: `gbrain put SLUG --file PATH` reads content from the file instead
-  // of silently swallowing the flag and creating an empty page.
-  test('put --file reads the stdin param (content) from a file', () => {
-    const dir = mkdtempSync(join(tmpdir(), 'gbrain-put-file-'));
-    try {
-      const pagePath = join(dir, 'page.md');
-      writeFileSync(pagePath, '# From file\n\nBody loaded from --file.\n');
-      const params = parseOpArgs(operationsByName.put_page, ['concepts/from-file', '--file', pagePath]);
-      expect(params.slug).toBe('concepts/from-file');
-      expect(params.content).toBe('# From file\n\nBody loaded from --file.\n');
-    } finally {
-      rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  // #380 regression guard: undeclared-but-honored flags must keep passing
-  // through when unknown flags become hard errors (--source is read by
-  // makeContext; --json by the output seam; --dry-run by ctx.dryRun).
-  test('pass-through allowlist flags survive on ops that do not declare them', () => {
-    const params = parseOpArgs(operationsByName.get_page, [
-      'people/alice-example', '--source', 'wiki', '--json', '--dry-run',
-    ]);
-    expect(params).toEqual({
-      slug: 'people/alice-example',
-      source: 'wiki',
-      json: true,
-      dry_run: true,
-    });
-  });
-
   test('--no-<boolean> maps to false without consuming the next flag', () => {
     const params = parseOpArgs(operationsByName.query, [
       'freshEmbedSourceScope code source',

test/cli.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from 'bun:test';
-import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
 
@@ -120,76 +120,6 @@ describe('CLI dispatch integration', () => {
     expect(exitCode).toBe(0);
   });
 
-  // #380 / PR #856: put --help documents the --file input path.
-  test('put --help documents --file input', async () => {
-    const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'put', '--help'], {
-      cwd: repoRoot,
-      stdout: 'pipe',
-      stderr: 'pipe',
-    });
-    const stdout = await new Response(proc.stdout).text();
-    const exitCode = await proc.exited;
-    expect(stdout).toContain('Usage: gbrain put');
-    expect(stdout).toContain('--file <path>');
-    expect(exitCode).toBe(0);
-  });
-
-  // #380: unknown flags on shared ops are a hard error (previously silently
-  // swallowed into params — `put --file` created empty pages). parseOpArgs
-  // runs BEFORE engine connect, so the error must fire without a brain.
-  test('unknown shared-op flags fail before DB connection', async () => {
-    const home = mkdtempSync(join(tmpdir(), 'gbrain-cli-unknown-flag-'));
-    try {
-      const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'get', 'people/alice', '--bogus'], {
-        cwd: repoRoot,
-        stdout: 'pipe',
-        stderr: 'pipe',
-        env: isolatedEnv(home),
-      });
-      const stderr = await new Response(proc.stderr).text();
-      const exitCode = await proc.exited;
-      expect(stderr).toContain('Unknown option for gbrain get: --bogus');
-      expect(stderr).not.toContain('No brain configured');
-      expect(exitCode).toBe(1);
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
-  });
-
-  test('put rejects combining --file and --content', async () => {
-    const home = mkdtempSync(join(tmpdir(), 'gbrain-cli-put-conflict-'));
-    try {
-      const pagePath = join(home, 'page.md');
-      writeFileSync(pagePath, 'file body\n');
-      const proc = Bun.spawn(
-        ['bun', 'run', 'src/cli.ts', 'put', 'a/b', '--content', 'inline', '--file', pagePath],
-        { cwd: repoRoot, stdout: 'pipe', stderr: 'pipe', env: isolatedEnv(home) },
-      );
-      const stderr = await new Response(proc.stderr).text();
-      const exitCode = await proc.exited;
-      expect(stderr).toContain('use only one of --file, --content, or stdin');
-      expect(exitCode).toBe(1);
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
-  });
-
-  test('put --file with a missing path errors instead of writing an empty page', async () => {
-    const home = mkdtempSync(join(tmpdir(), 'gbrain-cli-put-missing-file-'));
-    try {
-      const proc = Bun.spawn(
-        ['bun', 'run', 'src/cli.ts', 'put', 'a/b', '--file', join(home, 'nope.md')],
-        { cwd: repoRoot, stdout: 'pipe', stderr: 'pipe', env: isolatedEnv(home) },
-      );
-      const stderr = await new Response(proc.stderr).text();
-      const exitCode = await proc.exited;
-      expect(stderr).toContain('cannot read --file');
-      expect(exitCode).toBe(1);
-    } finally {
-      rmSync(home, { recursive: true, force: true });
-    }
-  });
-
   test('upgrade --help prints usage without running upgrade', async () => {
     const proc = Bun.spawn(['bun', 'run', 'src/cli.ts', 'upgrade', '--help'], {
       cwd: repoRoot,

test/cycle-dream-output-root.test.ts

@@ -26,6 +26,7 @@ const transcript: DiscoveredTranscript = {
   content: 'User: hello world',
   contentHash: 'abcdef0123456789',
   inferredDate: '2026-07-17',
+  transcriptSource: null,
 } as DiscoveredTranscript;
 
 describe('#2415: buildSynthesisPrompt output root', () => {

test/cycle-synthesize-slug-collection.test.ts

@@ -152,3 +152,94 @@ describe('#2569: stampDreamProvenance persists the marker into DB frontmatter',
     await stampDreamProvenance(engine as any, refs, '2026-07-17'); // idempotent
   });
 });
+
+describe('#2285: orchestrator-owned deterministic transcript frontmatter', () => {
+  const meta = {
+    idx: 1,
+    hash6: 'abc123',
+    chunkTotal: 3,
+    transcriptSource: 'claude-code',
+    transcriptId: 'session-uuid',
+    inferredDate: '2026-05-15',
+  };
+
+  test('collectChildPutPageSlugs pairs each ref back to the writing job', async () => {
+    const refs = await collectChildPutPageSlugs(
+      engine as any, [1001], new Map([[1001, { ...meta, chunkTotal: 1 }]]), 'mybrain',
+    );
+    expect(refs.length).toBeGreaterThan(0);
+    for (const r of refs) {
+      expect(r.jobId).toBe(1001);
+      expect(r.source_id).toBe('mybrain'); // #1586: cycle source, never hardcoded 'default'
+    }
+  });
+
+  test('slug collision across children attributes the LAST writer (matches surviving putPage)', async () => {
+    const db = (engine as any).db;
+    // Jobs 1001 then 1002 write the same slug; the pages row would hold
+    // 1002's content (last put_page wins), so the ref must carry jobId 1002.
+    await db.query(
+      `INSERT INTO subagent_tool_executions (job_id, message_idx, tool_use_id, tool_name, status, input)
+       VALUES (1001, 9, 'tool_dup_a', 'brain_put_page', 'complete', $1::jsonb)`,
+      [JSON.stringify({ slug: 'wiki/agents/test/collision', body: 'first' })],
+    );
+    await db.query(
+      `INSERT INTO subagent_tool_executions (job_id, message_idx, tool_use_id, tool_name, status, input)
+       VALUES (1002, 9, 'tool_dup_b', 'brain_put_page', 'complete', $1::jsonb)`,
+      [JSON.stringify({ slug: 'wiki/agents/test/collision', body: 'second' })],
+    );
+    const refs = await collectChildPutPageSlugs(engine as any, [1001, 1002], new Map());
+    const hit = refs.find((r: { slug: string }) => r.slug === 'wiki/agents/test/collision');
+    expect(hit?.jobId).toBe(1002);
+  });
+
+  test('stampDreamProvenance merges the transcript metadata into DB frontmatter', async () => {
+    const slug = 'wiki/originals/ideas/2026-07-17-transcript-meta-abc123';
+    await engine.putPage(slug, {
+      type: 'note',
+      title: 'Meta stamp',
+      compiled_truth: 'body',
+      timeline: '',
+      frontmatter: { keep_me: 'yes', transcript_id: 'subagent-drift' },
+    });
+    await stampDreamProvenance(
+      engine as any,
+      [{ slug, source_id: 'default', jobId: 42 }],
+      '2026-07-17',
+      new Map([[42, meta]]),
+    );
+    const rows = await engine.executeRaw<{ fm: Record<string, unknown> }>(
+      `SELECT frontmatter AS fm FROM pages WHERE slug = $1`, [slug],
+    );
+    const fm = rows[0].fm as Record<string, unknown>;
+    expect(fm.dream_generated).toBe(true);
+    expect(fm.dream_cycle_date).toBe('2026-07-17');
+    expect(fm.transcript_id).toBe('session-uuid'); // orchestrator wins over subagent drift
+    expect(fm.transcript_hash).toBe('abc123');
+    expect(fm.transcript_source).toBe('claude-code');
+    expect(fm.chunk).toBe('2/3');
+    expect(fm.date).toBe('2026-05-15');
+    expect(fm.keep_me).toBe('yes'); // subagent-owned keys survive
+  });
+
+  test('single-chunk children with no inferredDate stamp only the applicable fields', async () => {
+    const slug = 'wiki/originals/ideas/2026-07-17-minimal-meta-abc123';
+    await engine.putPage(slug, {
+      type: 'note', title: 'Minimal', compiled_truth: 'b', timeline: '', frontmatter: {},
+    });
+    await stampDreamProvenance(
+      engine as any,
+      [{ slug, source_id: 'default', jobId: 43 }],
+      '2026-07-17',
+      new Map([[43, { ...meta, chunkTotal: 1, transcriptSource: null, inferredDate: null }]]),
+    );
+    const rows = await engine.executeRaw<{ fm: Record<string, unknown> }>(
+      `SELECT frontmatter AS fm FROM pages WHERE slug = $1`, [slug],
+    );
+    const fm = rows[0].fm as Record<string, unknown>;
+    expect(fm.transcript_id).toBe('session-uuid');
+    expect(fm.chunk).toBeUndefined();
+    expect(fm.transcript_source).toBeUndefined();
+    expect(fm.date).toBeUndefined();
+  });
+});

test/cycle-synthesize.test.ts

@@ -302,6 +302,7 @@ describe('judgeSignificance', () => {
       content: 'A short conversation about something interesting.',
       basename: 'x',
       inferredDate: null,
+      transcriptSource: null,
     };
   }
 
@@ -415,6 +416,7 @@ describe('judgeSignificance — UTF-16 safety (v0.41.13)', () => {
       content,
       basename: 'long',
       inferredDate: null,
+      transcriptSource: null,
     };
   }
 

test/cycle/synthesize-gateway-adapter.test.ts

@@ -45,6 +45,7 @@ const FIXTURE_TRANSCRIPT: DiscoveredTranscript = {
   content: 'Synthetic transcript content for gateway-adapter parity tests.',
   contentHash: 'sha-fixture-1',
   inferredDate: '2026-05-24',
+  transcriptSource: null,
 };
 
 describe('makeJudgeClient — construction-time provider probe', () => {

test/cycle/transcript-discovery-metadata.test.ts

@@ -0,0 +1,109 @@
+/**
+ * #2285 — transcript metadata discovery.
+ *
+ * Pins the two discovery-side additions:
+ *   1. `transcriptSource` — derived from the `<source>/<date>/<file>` path
+ *      layout; null for ad-hoc inputs that don't match.
+ *   2. Content-based date inference — the `| First message | <ISO> |` row in
+ *      the transcript's `## Metadata` table wins over the filename-regex
+ *      date (stable across mtime-restamping re-syncs); filename is the
+ *      fallback.
+ *
+ * Pure filesystem; no engine, no LLM.
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname } from 'node:path';
+import {
+  discoverTranscripts,
+  readSingleTranscript,
+  deriveTranscriptSource,
+  inferContentDate,
+} from '../../src/core/cycle/transcript-discovery.ts';
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), 'gbrain-transcript-meta-'));
+});
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+function write(relPath: string, body: string): string {
+  const full = join(tmpDir, relPath);
+  mkdirSync(dirname(full), { recursive: true });
+  writeFileSync(full, body);
+  return full;
+}
+
+const FILLER = 'User: hello world. '.repeat(200);
+const METADATA_BLOCK =
+  '## Metadata\n\n| Key | Value |\n| --- | --- |\n| First message | 2026-05-15T03:51:11.584Z |\n\n';
+
+describe('deriveTranscriptSource', () => {
+  test('extracts the source slug from <source>/<date>/<file> layout', () => {
+    expect(deriveTranscriptSource('/corpus/claude-code/2026-06-12/abc.md')).toBe('claude-code');
+    expect(deriveTranscriptSource('/corpus/voice-notes/2026-06-12/xyz.md')).toBe('voice-notes');
+  });
+
+  test('null when the parent dir is not a date dir or grandparent is not a slug', () => {
+    expect(deriveTranscriptSource('/corpus/flat-file.md')).toBeNull();
+    expect(deriveTranscriptSource('/corpus/claude-code/not-a-date/abc.md')).toBeNull();
+    expect(deriveTranscriptSource('/corpus/Not A Slug/2026-06-12/abc.md')).toBeNull();
+  });
+});
+
+describe('inferContentDate', () => {
+  test('parses the | First message | row', () => {
+    expect(inferContentDate(METADATA_BLOCK)).toBe('2026-05-15');
+  });
+  test('null when absent', () => {
+    expect(inferContentDate(FILLER)).toBeNull();
+  });
+});
+
+describe('discoverTranscripts — transcriptSource + date cascade', () => {
+  test('populates transcriptSource per file; null for flat files', () => {
+    write('claude-code/2026-06-12/aaaa.md', FILLER);
+    write('2026-06-12-flat.md', FILLER);
+    const out = discoverTranscripts({ corpusDir: tmpDir, minChars: 100 });
+    const byBase = new Map(out.map(t => [t.basename, t.transcriptSource]));
+    expect(byBase.get('aaaa')).toBe('claude-code');
+    expect(byBase.get('2026-06-12-flat')).toBeNull();
+  });
+
+  test('content First-message date wins over the filename date', () => {
+    write('2026-01-01-named.md', METADATA_BLOCK + FILLER);
+    const out = discoverTranscripts({ corpusDir: tmpDir, minChars: 100 });
+    expect(out).toHaveLength(1);
+    expect(out[0].inferredDate).toBe('2026-05-15');
+  });
+
+  test('filename date remains the fallback when content has no metadata row', () => {
+    write('2026-01-01-named.md', FILLER);
+    const out = discoverTranscripts({ corpusDir: tmpDir, minChars: 100 });
+    expect(out[0].inferredDate).toBe('2026-01-01');
+  });
+
+  test('date filter matches on the content date for UUID-named transcripts', () => {
+    write('claude-code/2026-05-15/uuid-basename.md', METADATA_BLOCK + FILLER);
+    const hit = discoverTranscripts({ corpusDir: tmpDir, minChars: 100, date: '2026-05-15' });
+    expect(hit).toHaveLength(1);
+    const miss = discoverTranscripts({ corpusDir: tmpDir, minChars: 100, date: '2026-05-16' });
+    expect(miss).toHaveLength(0);
+  });
+});
+
+describe('readSingleTranscript — same metadata surface', () => {
+  test('carries transcriptSource and prefers the content date', () => {
+    const p = write('claude-code/2026-05-15/2026-01-01-single.md', METADATA_BLOCK + FILLER);
+    const t = readSingleTranscript(p, { minChars: 100 });
+    expect(t).not.toBeNull();
+    expect(t!.transcriptSource).toBe('claude-code');
+    expect(t!.inferredDate).toBe('2026-05-15');
+  });
+});

test/list-pages-offset.test.ts

@@ -1,55 +0,0 @@
-import { describe, test, expect } from 'bun:test';
-import { operationsByName } from '../src/core/operations.ts';
-
-/**
- * #2876: `gbrain list --limit` silently clamped at 100 with no pagination.
- * list_pages now declares `offset` (both engines already supported it on
- * PageFilters) and the limit description discloses the 100-row cap.
- */
-describe('list_pages pagination (#2876)', () => {
-  const listPagesOp = operationsByName.list_pages;
-
-  function makeCtx(captured: unknown[]) {
-    return {
-      engine: {
-        listPages: async (filters: unknown) => {
-          captured.push(filters);
-          return [];
-        },
-      },
-      config: { engine: 'pglite' },
-      logger: { info() {}, warn() {}, error() {} },
-      dryRun: false,
-      remote: false,
-      sourceId: 'default',
-    } as any;
-  }
-
-  test('declares offset param and discloses the 100-row cap on limit', () => {
-    expect(listPagesOp.params.offset).toBeDefined();
-    expect(listPagesOp.params.offset.type).toBe('number');
-    expect(listPagesOp.params.limit.description).toContain('100');
-  });
-
-  test('threads offset through to engine.listPages', async () => {
-    const captured: any[] = [];
-    await listPagesOp.handler(makeCtx(captured), { limit: 10, offset: 30 });
-    expect(captured[0].offset).toBe(30);
-    expect(captured[0].limit).toBe(10);
-  });
-
-  test('drops negative, non-finite, and zero offsets', async () => {
-    const captured: any[] = [];
-    const ctx = makeCtx(captured);
-    await listPagesOp.handler(ctx, { offset: -5 });
-    await listPagesOp.handler(ctx, { offset: Infinity });
-    await listPagesOp.handler(ctx, { offset: 0 });
-    for (const f of captured) expect(f.offset).toBeUndefined();
-  });
-
-  test('floors fractional offsets', async () => {
-    const captured: any[] = [];
-    await listPagesOp.handler(makeCtx(captured), { offset: 7.9 });
-    expect(captured[0].offset).toBe(7);
-  });
-});

test/progress.test.ts

@@ -216,17 +216,21 @@ describe('progress reporter', () => {
   });
 
   test('only one process-level signal handler installed across many reporters', () => {
-    // Baseline: one handler already installed by prior tests in this file.
+    // Baseline: one handler already installed by prior tests in this file, and
+    // possibly live reporters from OTHER test files sharing this bun process
+    // (shard composition is not this test's invariant — assert the delta, not
+    // an absolute zero, or shard reshuffles make this fail spuriously).
     const installedBefore = __signalHandlerInstalledForTest();
+    const liveBefore = __liveReporterCountForTest();
     const { stream } = sink(false);
     for (let i = 0; i < 50; i++) {
       const p = createProgress({ mode: 'json', stream, minIntervalMs: 0, minItems: 1 });
       p.start(`phase_${i}`, 1);
       p.finish();
     }
-    // After 50 reporter lifecycles, still exactly one handler and zero leaked live entries.
+    // After 50 reporter lifecycles, still exactly one handler and zero NET leaked live entries.
     expect(__signalHandlerInstalledForTest()).toBe(installedBefore || true);
-    expect(__liveReporterCountForTest()).toBe(0);
+    expect(__liveReporterCountForTest()).toBe(liveBefore);
   });
 
   test('startHeartbeat() fires heartbeats and stop() clears', async () => {