@ulysses-ai/create-workspace 0.13.0-beta.0

package/template/.claude/hooks/session-end.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// SessionEnd hook — mark this chat's `ended` timestamp in the session
+// tracker and append a small safety-net note to the session.md body.
+import { appendFileSync, mkdirSync, existsSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import {
+  getWorkspaceRoot,
+  readStdin,
+  readJSON,
+  respond,
+  getActiveSessionPointer,
+  getMainRoot,
+  readSessionTracker,
+  updateSessionTracker,
+  sessionFilePath,
+  sessionWorktreePath,
+  getWorkspacePaths,
+} from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const mainRoot = getMainRoot(root);
+const { scratchpadDir } = getWorkspacePaths(mainRoot);
+const logFile = join(scratchpadDir, 'session-log.jsonl');
+const settings = readJSON(join(root, '.claude', 'settings.local.json'));
+
+const input = await readStdin();
+const reason = input.reason || 'unknown';
+const sessionId = input.session_id || null;
+const user = settings?.workspace?.user || 'unknown';
+
+let branch = 'unknown';
+try {
+  branch = execSync('git branch --show-current', { cwd: root, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+} catch {}
+
+// Update session tracker: mark this chat as ended, append safety note
+const pointer = getActiveSessionPointer(root);
+if (pointer && sessionId) {
+  const tracker = readSessionTracker(mainRoot, pointer.name);
+  if (tracker) {
+    const chats = tracker.chatSessions || [];
+    const chat = chats.find(c => c.id === sessionId && c.ended === null);
+    if (chat) {
+      chat.ended = new Date().toISOString();
+      updateSessionTracker(mainRoot, pointer.name, {
+        chatSessions: chats,
+        updated: new Date().toISOString().slice(0, 10),
+      });
+    }
+
+    // Append a safety-net note to the session.md body so the next chat
+    // can see that a previous chat ended without capturing explicitly.
+    // The tracker lives inside the session worktree on the session branch,
+    // so the auto-commit must run from inside the worktree.
+    const trackerPath = sessionFilePath(mainRoot, pointer.name);
+    if (existsSync(trackerPath)) {
+      const timestamp = new Date().toISOString().slice(0, 19).replace('T', ' ');
+      const safetyEntry = `\n### Session ended (${timestamp})\n\nReason: ${reason}. Chat session ${sessionId || 'unknown'}.\n`;
+      appendFileSync(trackerPath, safetyEntry);
+
+      // Auto-commit from inside the worktree. Best-effort — non-fatal if
+      // the commit fails (hook blocked, nothing to commit, etc.).
+      try {
+        const worktreeCwd = sessionWorktreePath(mainRoot, pointer.name);
+        execSync('git add session.md', { cwd: worktreeCwd, stdio: 'pipe' });
+        execSync(
+          `git commit -m "chore: session-end safety capture for ${pointer.name}"`,
+          { cwd: worktreeCwd, stdio: 'pipe' }
+        );
+      } catch {
+        // Non-fatal
+      }
+    }
+  }
+}
+
+// Append to the workspace session log (disposable)
+if (!existsSync(scratchpadDir)) mkdirSync(scratchpadDir, { recursive: true });
+const entry = JSON.stringify({
+  event: 'session_end',
+  date: new Date().toISOString(),
+  user,
+  reason,
+  session_id: sessionId,
+  workspace_branch: branch,
+  work_session: pointer?.name || null,
+});
+appendFileSync(logFile, entry + '\n');
+
+respond();

package/template/.claude/hooks/session-start.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// SessionStart hook — register this chat in the active session tracker
+// and surface open sessions + shared context.
+import { readdirSync, statSync, readFileSync, existsSync } from 'fs';
+import { join, basename, relative } from 'path';
+import { execSync } from 'child_process';
+import {
+  getWorkspaceRoot,
+  readJSON,
+  readStdin,
+  respond,
+  getSessionTrackers,
+  getActiveSessionPointer,
+  readSessionTracker,
+  updateSessionTracker,
+  sessionFolderPath,
+  timeAgo,
+} from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const input = await readStdin();
+const config = readJSON(join(root, 'workspace.json'));
+
+const chatId = input.session_id || null;
+const contextDir = join(root, 'shared-context');
+const reposDir = join(root, 'repos');
+const lines = [];
+
+if (!config) {
+  respond('No workspace.json found. Run /workspace-init to initialize this workspace.');
+  process.exit(0);
+}
+
+lines.push(`Workspace: ${config.workspace?.name || 'unnamed'}`);
+
+// If we're inside a workspace worktree, its .claude/.active-session.json
+// tells us which session this is.
+const pointer = getActiveSessionPointer(root);
+if (pointer) {
+  if (chatId) {
+    const mainRoot = pointer.rootPath || root;
+    const tracker = readSessionTracker(mainRoot, pointer.name);
+    if (tracker) {
+      const chats = tracker.chatSessions || [];
+      if (!chats.some(c => c.id === chatId)) {
+        chats.push({
+          id: chatId,
+          names: [],
+          started: new Date().toISOString(),
+          ended: null,
+        });
+        updateSessionTracker(mainRoot, pointer.name, {
+          chatSessions: chats,
+          updated: new Date().toISOString().slice(0, 10),
+        });
+      }
+    }
+  }
+  lines.push(`Active work session: ${pointer.name}`);
+  lines.push(`Working in workspace worktree. Main root: ${pointer.rootPath}`);
+  respond(lines.join('\n'));
+  process.exit(0);
+}
+
+// We're at the main workspace root — surface open sessions and context.
+
+// Fetch project repos in the background (best effort)
+const repoNames = Object.keys(config.repos || {});
+const missing = [];
+const existing = [];
+for (const name of repoNames) {
+  const repoPath = join(reposDir, name);
+  if (existsSync(repoPath)) {
+    existing.push(name);
+    try {
+      execSync('git fetch --quiet', { cwd: repoPath, stdio: 'pipe', timeout: 10000 });
+    } catch {}
+  } else {
+    missing.push(name);
+  }
+}
+if (missing.length > 0) lines.push(`Missing repos: ${missing.join(', ')}. Run /workspace-init to clone them.`);
+if (existing.length > 0) lines.push(`Repos synced: ${existing.join(', ')}`);
+
+// Surface active work sessions
+const trackers = getSessionTrackers(root);
+if (trackers.length > 0) {
+  lines.push('');
+  lines.push('Active work sessions:');
+  for (let i = 0; i < trackers.length; i++) {
+    const t = trackers[i];
+    const wsWorktree = join(sessionFolderPath(root, t.name), 'workspace');
+    const worktreeExists = existsSync(wsWorktree);
+    if (!worktreeExists) {
+      lines.push(`  ${i + 1}. ${t.name} (orphaned — worktree missing)`);
+      continue;
+    }
+    const chats = t.chatSessions || [];
+    const lastChat = chats[chats.length - 1];
+    const lastEnded = lastChat?.ended;
+    const statusDetail = t.status === 'paused'
+      ? `paused ${timeAgo(lastEnded)}`
+      : lastEnded
+        ? `active, last chat ended ${timeAgo(lastEnded)}`
+        : 'active';
+    const repoList = Array.isArray(t.repos) ? t.repos.join(', ') : (t.repos || '—');
+    lines.push(`  ${i + 1}. ${t.name} (${statusDetail})`);
+    lines.push(`     "${t.description || ''}"`);
+    lines.push(`     Branch: ${t.branch} | Repos: ${repoList}`);
+    lines.push(`     Worktree: work-sessions/${t.name}/workspace/`);
+    lines.push('');
+  }
+  lines.push('Use /start-work to resume a session or start new work.');
+}
+
+// Surface shared context (secondary)
+if (existsSync(contextDir)) {
+  const entries = [];
+
+  function scanDir(dir, depth = 0) {
+    if (depth > 3) return;
+    for (const entry of readdirSync(dir)) {
+      const fullPath = join(dir, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        if (entry === 'locked' || entry === '.keep') continue;
+        scanDir(fullPath, depth + 1);
+      } else if (entry.endsWith('.md') && entry !== '.keep' && !entry.startsWith('local-only-')) {
+        const relPath = relative(contextDir, fullPath);
+        if (relPath.startsWith('locked/')) continue;
+        const content = readFileSync(fullPath, 'utf-8');
+        const topicMatch = content.match(/^topic:\s*(.+)$/m);
+        const lifecycleMatch = content.match(/^lifecycle:\s*(.+)$/m);
+        const topic = topicMatch ? topicMatch[1].trim() : basename(entry, '.md');
+        const lifecycle = lifecycleMatch ? lifecycleMatch[1].trim() : 'active';
+        const mtime = stat.mtime.toISOString().slice(0, 16).replace('T', ' ');
+        entries.push(`- ${topic} (${lifecycle}, updated ${mtime}) — ${relPath}`);
+      }
+    }
+  }
+
+  scanDir(contextDir);
+  if (entries.length > 0) {
+    lines.push('');
+    lines.push('Shared context:');
+    lines.push(...entries);
+  }
+}
+
+respond(lines.join('\n'));

package/template/.claude/hooks/subagent-start.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// SubagentStart hook — inject shared-context/locked/ into subagent context
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const config = readJSON(join(root, 'workspace.json'));
+const lockedDir = join(root, 'shared-context', 'locked');
+
+const maxBytes = config?.workspace?.subagentContextMaxBytes || 10240;
+
+if (!existsSync(lockedDir)) {
+  respond();
+  process.exit(0);
+}
+
+const files = readdirSync(lockedDir)
+  .filter(f => f.endsWith('.md') && f !== '.keep')
+  .sort();
+
+if (files.length === 0) {
+  respond();
+  process.exit(0);
+}
+
+let context = '';
+for (const file of files) {
+  const name = basename(file, '.md');
+  const content = readFileSync(join(lockedDir, file), 'utf-8');
+  context += `\n--- ${name} ---\n${content}\n`;
+}
+
+if (Buffer.byteLength(context) > maxBytes) {
+  const summary = files.map(f => {
+    const content = readFileSync(join(lockedDir, f), 'utf-8');
+    const firstLine = content.split('\n').find(l => l.trim() && !l.startsWith('---'))?.replace(/^#*\s*/, '') || '';
+    return `- ${basename(f, '.md')}: ${firstLine}`;
+  }).join('\n');
+
+  context = `[Locked shared context exceeds ${maxBytes} byte limit (${Buffer.byteLength(context)} bytes). Summary of ${files.length} files:]\n${summary}\n[Read individual files from shared-context/locked/ if you need full content.]`;
+}
+
+respond(context);

package/template/.claude/hooks/workspace-update-check.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+// SessionStart + PreToolUse hook — detect pending workspace update payload
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { getWorkspaceRoot, readJSON, respond } from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const payloadDir = join(root, '.workspace-update');
+
+// Fast bail if no payload exists
+if (!existsSync(payloadDir)) {
+  respond();
+  process.exit(0);
+}
+
+const manifest = readJSON(join(payloadDir, '.manifest.json'));
+const config = readJSON(join(root, 'workspace.json'));
+const initialized = config?.workspace?.initialized === true || !!config?.workspace?.templateVersion;
+const action = manifest?.action || (initialized ? 'upgrade' : 'init');
+const version = manifest?.templateVersion || 'unknown';
+
+// Check if payload is stale (older than 5 minutes = likely survived a previous session)
+const stale = manifest?.timestamp
+  ? (Date.now() - new Date(manifest.timestamp).getTime()) > 5 * 60 * 1000
+  : false;
+const urgency = stale
+  ? `URGENT: This update payload has been pending since ${manifest.timestamp}. It was not completed in a previous session. `
+  : '';
+const skipAudit = stale
+  ? 'Skip the pre-update audit and proceed directly to comparing and applying changes. '
+  : '';
+
+if (action === 'init' || !initialized) {
+  respond(`MANDATORY: ${urgency}A workspace init payload (template v${version}) is pending at .workspace-update/.
+Read .workspace-update/.claude/skills/workspace-init/SKILL.md and follow it before doing anything else.
+${skipAudit}Do not proceed with the user's request until initialization is complete.`);
+} else {
+  const from = manifest?.fromVersion || 'unknown';
+  respond(`MANDATORY: ${urgency}A workspace upgrade payload (v${from} → v${version}) is pending at .workspace-update/.
+Read .workspace-update/.claude/skills/workspace-update/SKILL.md and follow it before doing anything else.
+${skipAudit}Do not proceed with the user's request until the update is complete.`);
+}

package/template/.claude/hooks/worktree-create.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// WorktreeCreate hook — scan for stale worktrees across project repos and
+// flag them. Project worktrees live inside work-sessions/{name}/workspace/repos/
+// in the new layout. The scan walks each project repo's worktree admin list
+// rather than a filesystem pattern, so it keeps working regardless of where
+// worktrees are physically located.
+import { readdirSync, existsSync } from 'fs';
+import { join, basename } from 'path';
+import { execSync } from 'child_process';
+import { getWorkspaceRoot, respond } from './_utils.mjs';
+
+const root = getWorkspaceRoot(import.meta.url);
+const reposDir = join(root, 'repos');
+const stale = [];
+
+if (!existsSync(reposDir)) {
+  respond();
+  process.exit(0);
+}
+
+for (const entry of readdirSync(reposDir)) {
+  const repoPath = join(reposDir, entry);
+  if (!existsSync(join(repoPath, '.git'))) continue;
+
+  let worktreeOutput;
+  try {
+    worktreeOutput = execSync('git worktree list', { cwd: repoPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] });
+  } catch { continue; }
+
+  for (const line of worktreeOutput.trim().split('\n')) {
+    const parts = line.trim().split(/\s+/);
+    const wtPath = parts[0];
+    if (!wtPath || wtPath === repoPath) continue;
+    if (!existsSync(wtPath)) continue;
+
+    const branchMatch = line.match(/\[(.+?)\]/);
+    const branch = branchMatch ? branchMatch[1] : 'unknown';
+
+    try {
+      const lastCommit = execSync('git log -1 --format=%ci', { cwd: wtPath, encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+      const daysAgo = Math.floor((Date.now() - new Date(lastCommit).getTime()) / 86400000);
+      if (daysAgo > 3) {
+        stale.push(`- ${basename(wtPath)} (${branch}): no commits in ${daysAgo} days`);
+      }
+    } catch {}
+  }
+}
+
+if (stale.length > 0) {
+  respond(`Stale worktrees found:\n${stale.join('\n')}\n\nConsider cleaning up with: git worktree remove {path}`);
+} else {
+  respond();
+}

package/template/.claude/lib/session-frontmatter.mjs

@@ -0,0 +1,265 @@
+// Session frontmatter parser for work-sessions/{name}/session.md trackers.
+//
+// Reads and writes a small, opinionated subset of YAML scoped to the
+// fields the workspace actually uses. Lossless rewrites: when a field is
+// updated, only that field's lines are touched — every other byte of the
+// frontmatter and body is preserved.
+//
+// Supported value shapes:
+//   - flat scalars (string, number, null, boolean, ISO timestamps, UUIDs)
+//   - flat lists ("repos:\n  - one\n  - two")
+//   - lists of mappings ("chatSessions:\n  - id: x\n    names: [a, b]\n    ...")
+//   - inline lists ("names: [a, b]")
+//
+// Anything outside this subset throws. The parser is intentionally narrow.
+
+import { readFileSync, writeFileSync } from 'fs';
+
+const FM_DELIM = '---';
+
+export function readSessionFile(filePath) {
+  return parseSessionContent(readFileSync(filePath, 'utf-8'));
+}
+
+export function parseSessionContent(content) {
+  const lines = content.split('\n');
+  if (lines[0] !== FM_DELIM) {
+    throw new Error('No frontmatter found (file does not start with ---)');
+  }
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i] === FM_DELIM) { endIdx = i; break; }
+  }
+  if (endIdx === -1) {
+    throw new Error('No closing --- for frontmatter');
+  }
+  const fmLines = lines.slice(1, endIdx);
+  const bodyLines = lines.slice(endIdx + 1);
+  const body = bodyLines.join('\n');
+  const { fields, fieldRanges } = parseFmLines(fmLines);
+  return { fields, body, raw: { fmLines, fieldRanges } };
+}
+
+function parseFmLines(fmLines) {
+  const fields = {};
+  const fieldRanges = {};
+  let i = 0;
+  while (i < fmLines.length) {
+    const line = fmLines[i];
+    if (!line.trim() || line.startsWith('#')) { i++; continue; }
+    const m = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+    if (!m) { i++; continue; }
+    const key = m[1];
+    const valuePart = m[2];
+    const start = i;
+
+    if (valuePart === '') {
+      // Block: either flat list, list of mappings, or empty scalar
+      i++;
+      const items = [];
+      while (i < fmLines.length) {
+        const next = fmLines[i];
+        if (next.startsWith('  - ')) {
+          const itemFirstLine = next.slice(4);
+          const mapMatch = itemFirstLine.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+          if (mapMatch) {
+            const item = {};
+            item[mapMatch[1]] = parseScalar(mapMatch[2]);
+            i++;
+            while (i < fmLines.length && fmLines[i].startsWith('    ')) {
+              const subLine = fmLines[i].slice(4);
+              const subMatch = subLine.match(/^([a-zA-Z_][a-zA-Z0-9_]*):\s*(.*)$/);
+              if (subMatch) item[subMatch[1]] = parseScalar(subMatch[2]);
+              i++;
+            }
+            items.push(item);
+          } else {
+            items.push(parseScalar(itemFirstLine));
+            i++;
+          }
+        } else {
+          break;
+        }
+      }
+      if (items.length === 0) {
+        fields[key] = null;
+        fieldRanges[key] = { start, end: start };
+      } else {
+        fields[key] = items;
+        fieldRanges[key] = { start, end: i - 1 };
+      }
+    } else {
+      fields[key] = parseScalar(valuePart);
+      fieldRanges[key] = { start, end: start };
+      i++;
+    }
+  }
+  return { fields, fieldRanges };
+}
+
+function parseScalar(s) {
+  s = s.trim();
+  if (s === '' || s === '~' || /^null$/i.test(s)) return null;
+  if (/^true$/i.test(s)) return true;
+  if (/^false$/i.test(s)) return false;
+  if (/^-?\d+$/.test(s)) return parseInt(s, 10);
+  if (/^-?\d+\.\d+$/.test(s)) return parseFloat(s);
+  if (s.startsWith('[') && s.endsWith(']')) {
+    const inner = s.slice(1, -1).trim();
+    if (inner === '') return [];
+    return inner.split(',').map(p => parseScalar(p.trim()));
+  }
+  if ((s.startsWith('"') && s.endsWith('"')) || (s.startsWith("'") && s.endsWith("'"))) {
+    return s.slice(1, -1);
+  }
+  return s;
+}
+
+function serializeFieldLines(key, value) {
+  if (value === null || value === undefined) return [`${key}: null`];
+  if (typeof value === 'boolean' || typeof value === 'number') return [`${key}: ${value}`];
+  if (typeof value === 'string') {
+    if (needsQuoting(value)) return [`${key}: "${escapeQuoted(value)}"`];
+    return [`${key}: ${value}`];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) return [`${key}: []`];
+    if (value.every(v => typeof v !== 'object' || v === null)) {
+      return [`${key}:`, ...value.map(v => `  - ${serializeInlineScalar(v)}`)];
+    }
+    const lines = [`${key}:`];
+    for (const item of value) {
+      let firstKey = true;
+      for (const [k, v] of Object.entries(item)) {
+        if (firstKey) {
+          lines.push(`  - ${k}: ${serializeMappingValue(v)}`);
+          firstKey = false;
+        } else {
+          lines.push(`    ${k}: ${serializeMappingValue(v)}`);
+        }
+      }
+    }
+    return lines;
+  }
+  throw new Error(`Cannot serialize ${typeof value} as field ${key}`);
+}
+
+function serializeMappingValue(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  if (Array.isArray(v)) {
+    return '[' + v.map(serializeInlineScalar).join(', ') + ']';
+  }
+  if (typeof v === 'string') {
+    if (needsQuoting(v)) return `"${escapeQuoted(v)}"`;
+    return v;
+  }
+  throw new Error(`Cannot serialize mapping value of type ${typeof v}`);
+}
+
+function serializeInlineScalar(v) {
+  if (v === null || v === undefined) return 'null';
+  if (typeof v === 'boolean' || typeof v === 'number') return String(v);
+  if (typeof v === 'string') {
+    if (needsInlineQuoting(v)) return `"${escapeQuoted(v)}"`;
+    return v;
+  }
+  throw new Error(`Cannot inline-serialize ${typeof v}`);
+}
+
+function needsQuoting(s) {
+  if (s === '') return true;
+  if (/^(true|false|null|yes|no|on|off|~)$/i.test(s)) return true;
+  if (/^-?\d+(\.\d+)?$/.test(s)) return true;
+  if (/^[\[\]{}!&*>|'"`@%?,]/.test(s)) return true;
+  if (s === '-' || s.startsWith('- ')) return true;
+  if (s.includes(': ')) return true;
+  if (s.endsWith(':')) return true;
+  if (s.includes(' #')) return true;
+  if (s !== s.trim()) return true;
+  return false;
+}
+
+function needsInlineQuoting(s) {
+  if (needsQuoting(s)) return true;
+  // Inside [a, b], commas would split the value
+  if (s.includes(',')) return true;
+  if (s.includes(']')) return true;
+  if (s.includes('[')) return true;
+  return false;
+}
+
+function escapeQuoted(s) {
+  return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+// === Public write API ===
+
+/**
+ * Update specific fields in a session file's frontmatter.
+ * Lossless for unchanged fields and the body. Fields set to `undefined`
+ * are removed. Fields not present in the file are appended.
+ */
+export function updateSessionFile(filePath, updates) {
+  const content = readFileSync(filePath, 'utf-8');
+  const newContent = updateSessionContent(content, updates);
+  if (newContent !== content) writeFileSync(filePath, newContent);
+}
+
+export function updateSessionContent(content, updates) {
+  const parsed = parseSessionContent(content);
+  const { fmLines, fieldRanges } = parsed.raw;
+  let newFmLines = [...fmLines];
+
+  // Process replacements/removals from bottom to top so line indices stay valid
+  const replacements = [];
+  const appends = [];
+  for (const [key, value] of Object.entries(updates)) {
+    if (fieldRanges[key]) {
+      replacements.push({ range: fieldRanges[key], key, value });
+    } else if (value !== undefined) {
+      appends.push({ key, value });
+    }
+  }
+  replacements.sort((a, b) => b.range.start - a.range.start);
+  for (const op of replacements) {
+    const removeCount = op.range.end - op.range.start + 1;
+    if (op.value === undefined) {
+      newFmLines.splice(op.range.start, removeCount);
+    } else {
+      const newLines = serializeFieldLines(op.key, op.value);
+      newFmLines.splice(op.range.start, removeCount, ...newLines);
+    }
+  }
+  for (const op of appends) {
+    newFmLines.push(...serializeFieldLines(op.key, op.value));
+  }
+
+  const reconstructed = ['---', ...newFmLines, '---'];
+  if (parsed.body === '') {
+    reconstructed.push('');
+  } else {
+    reconstructed.push(parsed.body);
+  }
+  return reconstructed.join('\n');
+}
+
+/**
+ * Create a session file from scratch with the given fields and body.
+ * Field order follows the order of keys in the fields object.
+ */
+export function writeSessionFile(filePath, fields, body = '') {
+  const fmLines = [];
+  for (const [key, value] of Object.entries(fields)) {
+    fmLines.push(...serializeFieldLines(key, value));
+  }
+  const lines = ['---', ...fmLines, '---', '', body];
+  writeFileSync(filePath, lines.join('\n'));
+}
+
+/**
+ * Convenience: read just the parsed fields object.
+ */
+export function readSessionFields(filePath) {
+  return readSessionFile(filePath).fields;
+}