@ulysses-ai/create-workspace 0.17.0-beta.0 → 0.19.0-beta.0

package/template/{.claude → _claude}/scripts/build-workspace-context.mjs

@@ -9,12 +9,14 @@
 // Source of truth: the filesystem. Hand edits are overwritten on regeneration.
 // Gitignored files are excluded automatically. .indexignore adds prefix excludes.
 //
-// Canonical files honor a configurable byte budget. Each locked file declares
+// Canonical files honor an opt-in byte budget. Each locked file declares
 // `priority: critical | reference` in its frontmatter (default: critical).
 // Section-level `<!-- canonical:trim --> ... <!-- canonical:end-trim -->` markers
-// fence droppable spans inside reference files. When canonical body bytes exceed
-// the budget, the builder trims reference files first, then stubs them, in that
-// deterministic order. Critical files are never modified.
+// fence droppable spans inside reference files. When a budget is set and the
+// canonical body exceeds it, the builder trims reference files first, then
+// stubs them, in that deterministic order. Critical files are never modified.
+// `workspace.canonicalBudgetBytes` is off unless it holds a number: absent or
+// null means every locked file ships in full and nothing is trimmed.
 //
 // Usage:
 //   node build-workspace-context.mjs --write [--root <workspace-root>]
@@ -25,10 +27,11 @@
 //   0 — all artifacts current and canonical within budget
 //   1 — at least one artifact missing or stale (regenerate via --write)
 //   2 — artifacts current, but canonical body exceeds budget after trimming and stubbing
+//       (only reachable when a budget is set; off means nothing can exceed it)
 // Stale wins over over-budget when both apply.
 
 import { readFileSync, writeFileSync, readdirSync, statSync, existsSync, realpathSync } from 'node:fs';
-import { join, relative, sep } from 'node:path';
+import { join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { parseSessionContent } from '../lib/session-frontmatter.mjs';
@@ -129,6 +132,15 @@ function gitIgnoredPaths(workspaceRoot, paths) {
   );
 }
 
+// The git filter fails open: gitIgnoredPaths returns an empty set when git is missing,
+// the directory is not a repository, or the subprocess errors. Canonical content is
+// committed and broadcast to every session and subagent, so that path must not depend on a
+// subprocess succeeding. Exclude the local-only-* convention by name as well.
+function isLocalOnlyName(filePath) {
+  const name = filePath.split(sep).pop() || '';
+  return name.startsWith('local-only-');
+}
+
 function stripFrontmatter(content) {
   if (!content.startsWith('---\n')) return content;
   const end = content.indexOf('\n---\n', 4);
@@ -159,7 +171,7 @@ function buildSharedIndex(workspaceRoot) {
     const relToWC = relative(wcRoot, f).split(sep).join('/');
     if (relToWC === INDEX_FILENAME || relToWC === CANONICAL_FILENAME) continue;
     if (isIgnored(relToWC, ignorePrefixes)) continue;
-    if (gitIgnored.has(candidatePaths[i])) continue;
+    if (gitIgnored.has(candidatePaths[i]) || isLocalOnlyName(f)) continue;
     const isLocked = relToWC.startsWith(`${SHARED_DIR}/${LOCKED_DIR}/`);
     const { description } = describeAndPath(f, wcRoot);
     entries.push({ rel: relToWC, isLocked, description });
@@ -171,11 +183,10 @@ function buildSharedIndex(workspaceRoot) {
   return entries;
 }
 
-function renderSharedIndex(entries, generatedAt) {
+function renderSharedIndex(entries) {
   const lines = [
     '---',
     'type: index',
-    `generated: ${generatedAt}`,
     '---',
     '',
     '# workspace-context — index',
@@ -293,16 +304,19 @@ export function extractCanonicalVariants({ name, rawContent }) {
 }
 
 /**
- * Read `workspace.canonicalBudgetBytes` from `workspace.json`.
+ * Read `workspace.canonicalBudgetBytes` from `workspace.json`. The budget is
+ * opt-in — the whole always-loaded set is measured by `alwaysLoadedBudgetBytes`
+ * instead, so a canonical-only ceiling is something a workspace opts into.
  * Returns:
- *   - The integer value when set to a non-negative integer.
- *   - 0 when set to 0 or a negative number (treated as disabled).
- *   - DEFAULT_CANONICAL_BUDGET when the field is absent or workspace.json is missing.
+ *   - 0 when the field is absent or `null`, or workspace.json is missing (off).
+ *   - 0 when set to 0 or a negative number (treated as off).
+ *   - The integer value when set to a positive number.
+ *   - DEFAULT_CANONICAL_BUDGET when set to a non-number (invalid, rejected as before).
  *   - DEFAULT_CANONICAL_BUDGET (with a stderr warning) when workspace.json fails to parse.
  */
 export function readWorkspaceBudget(workspaceRoot) {
   const path = join(workspaceRoot, 'workspace.json');
-  if (!existsSync(path)) return DEFAULT_CANONICAL_BUDGET;
+  if (!existsSync(path)) return 0;
   let parsed;
   try {
     parsed = JSON.parse(readFileSync(path, 'utf-8'));
@@ -311,9 +325,10 @@ export function readWorkspaceBudget(workspaceRoot) {
     return DEFAULT_CANONICAL_BUDGET;
   }
   const ws = parsed && typeof parsed === 'object' ? parsed.workspace : null;
-  if (!ws || typeof ws !== 'object') return DEFAULT_CANONICAL_BUDGET;
-  if (!('canonicalBudgetBytes' in ws)) return DEFAULT_CANONICAL_BUDGET;
+  if (!ws || typeof ws !== 'object') return 0;
+  if (!('canonicalBudgetBytes' in ws)) return 0;
   const v = ws.canonicalBudgetBytes;
+  if (v === null) return 0;
   if (typeof v !== 'number' || !Number.isFinite(v)) return DEFAULT_CANONICAL_BUDGET;
   if (v <= 0) return 0;
   return Math.floor(v);
@@ -351,7 +366,8 @@ export function renderCanonicalBody(resolvedItems) {
  *   4. Keep stage-3 resolution; status `over-budget`, overBy populated.
  *
  * Special cases:
- *   - budgetBytes <= 0: stage 1 always wins, selection.budgetBytes = null.
+ *   - budgetBytes <= 0 (off — absent, null, 0, or negative): stage 1 always
+ *     wins, selection.budgetBytes = null.
  *   - No reference items present and stage 1 fails: status `over-budget`,
  *     no transformation possible. Stderr warning is emitted.
  */
@@ -372,7 +388,7 @@ export function selectCanonicalContent(items, budgetBytes, opts) {
     return { name: item.name, priority: item.priority, content: item.full };
   });
 
-  // Disabled-budget path.
+  // No-budget path (off because unset, or explicitly disabled).
   if (!Number.isFinite(budgetBytes) || budgetBytes <= 0) {
     const resolved = resolveAt(1);
     return {
@@ -470,7 +486,16 @@ export function selectCanonicalContent(items, budgetBytes, opts) {
 function buildCanonical(workspaceRoot) {
   const lockedDir = join(workspaceRoot, WC_DIR, SHARED_DIR, LOCKED_DIR);
   if (!existsSync(lockedDir)) return [];
-  const files = walkMarkdown(lockedDir).filter((f) => !f.endsWith('.keep')).sort();
+  const candidates = walkMarkdown(lockedDir).filter((f) => !f.endsWith('.keep')).sort();
+  // canonical.md is committed and loaded verbatim into every session prompt, so a
+  // gitignored file under shared/locked/ must never reach it. The index builder applies
+  // this same filter; without it here, a local-only-*.md dropped into this directory is
+  // published to the repo and broadcast to every session.
+  const candidatePaths = candidates.map((f) => relative(workspaceRoot, f).split(sep).join('/'));
+  const gitIgnored = gitIgnoredPaths(workspaceRoot, candidatePaths);
+  const files = candidates.filter(
+    (f, i) => !gitIgnored.has(candidatePaths[i]) && !isLocalOnlyName(f),
+  );
   const items = [];
   for (const f of files) {
     const name = f.split(sep).pop().replace(/\.md$/, '');
@@ -501,9 +526,9 @@ function summarizeSelection(selection) {
   return `over budget by ${selection.overBy} bytes`;
 }
 
-function renderCanonical(resolvedItems, selection, generatedAt) {
+function renderCanonical(resolvedItems, selection) {
   const showBudget = selection && selection.budgetBytes !== null && selection.budgetBytes !== undefined;
-  const fmLines = ['---', 'type: canonical', `generated: ${generatedAt}`];
+  const fmLines = ['---', 'type: canonical'];
   if (showBudget) {
     fmLines.push(`budget: ${selection.budgetBytes}`);
     fmLines.push(`status: ${selection.status}`);
@@ -520,6 +545,8 @@ function renderCanonical(resolvedItems, selection, generatedAt) {
     lines.push(
       `> Budget: ${selection.budgetBytes} bytes (body); current: ${selection.currentBytes} bytes; status: ${selection.status} (${summarizeSelection(selection)}).`,
     );
+  } else if (selection) {
+    lines.push(`> Budget: off; current: ${selection.currentBytes} bytes.`);
   }
   lines.push('');
 
@@ -556,11 +583,10 @@ function buildTeamMemberIndex(workspaceRoot, user) {
   return entries;
 }
 
-function renderTeamMemberIndex(user, entries, generatedAt) {
+function renderTeamMemberIndex(user, entries) {
   const lines = [
     '---',
     'type: index',
-    `generated: ${generatedAt}`,
     '---',
     '',
     `# ${user}'s context`,
@@ -590,6 +616,23 @@ function listTeamMembers(workspaceRoot) {
 
 // ---------- orchestration ----------
 
+// Artifacts no longer carry a `generated:` line — it changed on every build,
+// nothing read it, and it made every long-lived branch conflict on files whose
+// content was identical (gh:132). This filter stays so a checkout still holding
+// a pre-fix artifact compares clean on body rather than reporting false staleness.
+// An artifact git is configured to ignore is regenerated per machine, so its
+// absence is expected rather than a failure. Falls back to treating the file
+// as tracked when git is unavailable, which keeps the stricter behaviour.
+function isUntrackedArtifact(root, absPath) {
+  const rel = relative(root, absPath).split(sep).join('/');
+  const r = spawnSync('git', ['-C', root, 'check-ignore', '-q', rel], { encoding: 'utf-8' });
+  return r.status === 0;
+}
+
+function workspaceRootOf(root) {
+  return resolve(root);
+}
+
 function fingerprint(content) {
   return content
     .split('\n')
@@ -597,7 +640,7 @@ function fingerprint(content) {
     .join('\n');
 }
 
-function regenerateAll(workspaceRoot, generatedAt) {
+function regenerateAll(workspaceRoot) {
   const wcRoot = join(workspaceRoot, WC_DIR);
   if (!existsSync(wcRoot)) return [];
 
@@ -606,7 +649,7 @@ function regenerateAll(workspaceRoot, generatedAt) {
   out.push({
     path: join(wcRoot, INDEX_FILENAME),
     label: 'index.md',
-    content: renderSharedIndex(sharedEntries, generatedAt) + '\n',
+    content: renderSharedIndex(sharedEntries) + '\n',
   });
 
   const canonicalItems = buildCanonical(workspaceRoot);
@@ -617,7 +660,7 @@ function regenerateAll(workspaceRoot, generatedAt) {
   out.push({
     path: join(wcRoot, CANONICAL_FILENAME),
     label: 'canonical.md',
-    content: renderCanonical(resolvedItems, selection, generatedAt) + '\n',
+    content: renderCanonical(resolvedItems, selection) + '\n',
     selection,
   });
 
@@ -626,7 +669,7 @@ function regenerateAll(workspaceRoot, generatedAt) {
     out.push({
       path: join(wcRoot, TEAM_MEMBER_DIR, user, INDEX_FILENAME),
       label: `team-member/${user}/index.md`,
-      content: renderTeamMemberIndex(user, entries, generatedAt),
+      content: renderTeamMemberIndex(user, entries),
     });
   }
 
@@ -640,7 +683,8 @@ function regenerateAll(workspaceRoot, generatedAt) {
  *   0 — all artifacts current and canonical body is within budget.
  *   1 — at least one artifact is missing or stale on disk. Run `--write`.
  *   2 — artifacts are current but canonical body exceeds budget after
- *       trimming and stubbing eligible reference files. Triage via
+ *       trimming and stubbing eligible reference files (only reachable when
+ *       a budget is set — off means nothing can exceed it). Triage via
  *       `/maintenance cleanup`. If both stale and over-budget, exit 1.
  *
  * `--write` always exits 0 on successful regeneration; over-budget is
@@ -648,14 +692,22 @@ function regenerateAll(workspaceRoot, generatedAt) {
  */
 function main() {
   const args = parseArgs(process.argv);
-  const generatedAt = new Date().toISOString();
-  const artifacts = regenerateAll(args.root, generatedAt);
+  const artifacts = regenerateAll(args.root);
 
   if (args.mode === 'check') {
     const stale = [];
     const missing = [];
+    const regenerable = [];
     for (const a of artifacts) {
-      if (!existsSync(a.path)) { missing.push(a.label); continue; }
+      if (!existsSync(a.path)) {
+        // Per-user indexes are gitignored (gh:132): absent is the normal state
+        // on a fresh checkout, not a staleness failure. Reporting them as
+        // missing would make --check, and therefore /maintenance and CI, fail
+        // on every clone. They are regenerated on demand instead.
+        if (isUntrackedArtifact(workspaceRootOf(args.root), a.path)) regenerable.push(a.label);
+        else missing.push(a.label);
+        continue;
+      }
       const onDisk = readFileSync(a.path, 'utf-8');
       if (fingerprint(onDisk) !== fingerprint(a.content)) stale.push(a.label);
     }
@@ -674,6 +726,7 @@ function main() {
     if (missing.length === 0 && stale.length === 0) {
       const overBudget = sel && sel.status === 'over-budget';
       const payload = { status: 'current', missing: [], stale: [] };
+      if (regenerable.length) payload.regenerable = regenerable;
       if (canonicalBlock) payload.canonical = canonicalBlock;
       payload.artifacts = artifacts.length;
       process.stdout.write(JSON.stringify(payload) + '\n');
@@ -681,6 +734,7 @@ function main() {
     }
 
     const payload = { status: 'stale', missing, stale };
+    if (regenerable.length) payload.regenerable = regenerable;
     if (canonicalBlock) payload.canonical = canonicalBlock;
     process.stdout.write(JSON.stringify(payload) + '\n');
     process.exit(1);
@@ -709,4 +763,6 @@ export {
   fingerprint,
   readDescription,
   stripFrontmatter,
+  gitIgnoredPaths,
+  isLocalOnlyName,
 };

package/template/_claude/scripts/chat-record.mjs

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+// The chat record: one file per long-lived chat, holding what that chat owns.
+//
+// The framework assumed one task spanning many chats and built a folder and a
+// tracker file around it. Practice is one chat spanning many tasks (gh:132).
+// The durable per-chat state is small — a declared scope, the concerns it
+// subscribes to, and the tasks currently open under it — and it is
+// machine-local, because chats are.
+//
+// Keyed on sessionId, filed under the chat name. Claude Code lets a session be
+// renamed at any time, so a record keyed only by name is orphaned by a rename
+// and a record keyed only by id is unreadable. The session registry carries
+// both, so the record carries both: the filename stays legible, and
+// reconcile() renames it when the chat's name changes.
+//
+// Lives in workspace-scratchpad/ because it is machine-local and regenerable —
+// losing it costs one re-declaration of scope, not the work.
+//
+// Usage:
+//   node chat-record.mjs --root <dir> --list
+//   node chat-record.mjs --root <dir> --read  <chat-name>
+//   node chat-record.mjs --root <dir> --reconcile --session-id <id> --name <n>
+//   node chat-record.mjs --root <dir> --whoami
+//   node chat-record.mjs --root <dir> --add-task    --chat <n> --work-item <id> --branch <b> [--repo <r>]
+//   node chat-record.mjs --root <dir> --remove-task --chat <n> --work-item <id> [--repo <r>]
+//
+// --add-task / --remove-task report `action`: "added" | "updated" for
+// --add-task, "removed" | "unchanged" for --remove-task. They also keep the
+// older `updated` boolean / `removed` count fields — `updated` means "an
+// existing entry was replaced", not "anything changed" — but new callers
+// should read `action`. --whoami prints this chat's record name by matching
+// $CLAUDE_CODE_SESSION_ID against the records' sessionId, nothing and exit
+// 1 when there is no match: the `Chat record:` hook line can be missing
+// after context compaction, and this is the recovery path.
+
+import {
+  readFileSync, writeFileSync, existsSync, mkdirSync,
+  readdirSync, renameSync, rmSync, realpathSync,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+function isMainModule(metaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(metaUrl)) === realpathSync(process.argv[1]);
+  } catch { return false; }
+}
+
+const CHATS_DIR = join('workspace-scratchpad', 'chats');
+
+function chatsDir(root) {
+  return join(resolve(root), CHATS_DIR);
+}
+
+function recordPath(root, chatName) {
+  return join(chatsDir(root), `${chatName}.json`);
+}
+
+// The chat drawer: in-progress designs, braindumps and research that should not
+// reach other chats until promoted. This is why local-only-* piles up at
+// workspace roots today — capture skills invoked from the launcher have nowhere
+// chat-scoped to write.
+function drawerPath(root, chatName) {
+  return join(chatsDir(root), chatName);
+}
+
+function emptyRecord(chatName, sessionId) {
+  return {
+    chat: chatName,
+    sessionId,
+    scope: { epic: null, labels: [], paths: [] },
+    concerns: [],
+    tasks: [],
+  };
+}
+
+function readRecord(root, chatName) {
+  const p = recordPath(root, chatName);
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, 'utf-8'));
+  } catch {
+    // A corrupt record is machine-local and regenerable. Refusing to start a
+    // session over it would be worse than losing a scope declaration.
+    return null;
+  }
+}
+
+function writeRecord(root, record) {
+  if (!record || !record.chat) throw new Error('writeRecord: record.chat is required');
+  const dir = chatsDir(root);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(recordPath(root, record.chat), `${JSON.stringify(record, null, 2)}\n`);
+  return recordPath(root, record.chat);
+}
+
+function listRecords(root) {
+  const dir = chatsDir(root);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((n) => n.endsWith('.json'))
+    .map((n) => readRecord(root, n.slice(0, -5)))
+    .filter(Boolean);
+}
+
+/**
+ * Bring the records on disk into line with the live session.
+ *
+ * - A record whose `sessionId` matches but whose filename does not is renamed:
+ *   the chat was renamed, and the state follows it.
+ * - A record with no matching live session is stale. When `liveSessionIds` is
+ *   supplied it is pruned; when it is not, pruning is skipped entirely rather
+ *   than guessed at — deleting state on incomplete information is worse than
+ *   leaving it.
+ */
+function reconcile(root, { sessionId, name, liveSessionIds = null } = {}) {
+  if (!sessionId || !name) throw new Error('reconcile: sessionId and name are required');
+  const result = { renamed: null, created: false, pruned: [] };
+
+  const existing = listRecords(root);
+  const mine = existing.find((r) => r.sessionId === sessionId);
+
+  if (mine && mine.chat !== name) {
+    const oldName = mine.chat;
+    const from = recordPath(root, oldName);
+    const to = recordPath(root, name);
+
+    mine.chat = name;
+    writeRecord(root, mine);
+    if (existsSync(from) && from !== to) rmSync(from);
+
+    // The drawer travels with the record. A rename that leaves captures behind
+    // under the old name strands them somewhere nothing looks.
+    const drawerFrom = drawerPath(root, oldName);
+    const drawerTo = drawerPath(root, name);
+    if (existsSync(drawerFrom) && !existsSync(drawerTo)) renameSync(drawerFrom, drawerTo);
+
+    result.renamed = { from: oldName, to: name };
+  } else if (!mine) {
+    writeRecord(root, emptyRecord(name, sessionId));
+    result.created = true;
+  }
+
+  if (Array.isArray(liveSessionIds)) {
+    for (const r of listRecords(root)) {
+      if (r.sessionId === sessionId) continue;
+      if (!liveSessionIds.includes(r.sessionId)) {
+        rmSync(recordPath(root, r.chat), { force: true });
+        result.pruned.push(r.chat);
+      }
+    }
+  }
+  return result;
+}
+
+
+// Claude Code's session registry: one file per running process, carrying both
+// the stable sessionId and the current, renameable name.
+//
+// Note what this is NOT: a list of chats that exist. It holds only processes
+// running right now, so a chat the operator closed looks exactly like one that
+// never existed. That is why reconcile() will not prune from it unless a caller
+// explicitly says to.
+function readSessionRegistry(homeDir = homedir()) {
+  const dir = join(homeDir, '.claude', 'sessions');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const name of readdirSync(dir)) {
+    if (!name.endsWith('.json')) continue;
+    try {
+      const rec = JSON.parse(readFileSync(join(dir, name), 'utf-8'));
+      if (rec && rec.sessionId) out.push(rec);
+    } catch { /* a half-written registry file is not our problem to fix */ }
+  }
+  return out;
+}
+
+/**
+ * Decide the name a chat's record should live under. The registry's name
+ * wins when it has one; otherwise an existing record for the same
+ * sessionId keeps its own name — a chat the registry has not named yet
+ * must not have its named record relabeled with the raw UUID. A genuinely
+ * new, unnamed chat falls back to the id so a record still exists.
+ */
+function resolveChatName(root, { sessionId, registryName = null } = {}) {
+  if (registryName) return registryName;
+  const existing = listRecords(root).find((r) => r.sessionId === sessionId);
+  return existing ? existing.chat : sessionId;
+}
+
+
+// A task is a tracker issue plus a branch plus the repo it lands in. It is
+// created on demand and disappears when it merges — nothing about it is
+// durable except the issue and the commits, so the record holds only the
+// pointer, never a copy of the issue.
+//
+// Identity is workItem + repo: the same issue can legitimately be open against
+// two repos in a multi-repo task, and re-recording the same one must update
+// rather than duplicate. /start-work is not always run exactly once.
+function addTask(root, chatName, { workItem, branch, repo = null } = {}) {
+  if (!workItem) throw new Error('addTask: workItem is required');
+  if (!branch) throw new Error('addTask: branch is required');
+  const rec = readRecord(root, chatName);
+  if (!rec) throw new Error(`addTask: no chat record for "${chatName}"`);
+  const i = rec.tasks.findIndex((t) => t.workItem === workItem && (t.repo ?? null) === repo);
+  const task = { workItem, branch, repo };
+  if (i >= 0) rec.tasks[i] = task;
+  else rec.tasks.push(task);
+  writeRecord(root, rec);
+  return { record: rec, action: i >= 0 ? 'updated' : 'added', updated: i >= 0 };
+}
+
+function removeTask(root, chatName, { workItem, repo = null } = {}) {
+  if (!workItem) throw new Error('removeTask: workItem is required');
+  const rec = readRecord(root, chatName);
+  if (!rec) throw new Error(`removeTask: no chat record for "${chatName}"`);
+  const before = rec.tasks.length;
+  rec.tasks = rec.tasks.filter((t) => !(t.workItem === workItem && (t.repo ?? null) === repo));
+  writeRecord(root, rec);
+  return { record: rec, action: before - rec.tasks.length > 0 ? 'removed' : 'unchanged', removed: before - rec.tasks.length };
+}
+
+// The record name for the chat running now. The SessionStart hook injects
+// a `Chat record:` line, but compaction can drop it; the sessionId the
+// hook keyed on is stable, so matching it against the records recovers the
+// name without guessing. Null when the env var is unset or nothing matches.
+function whoami(root, { env = process.env } = {}) {
+  const sid = env.CLAUDE_CODE_SESSION_ID;
+  if (!sid) return null;
+  const mine = listRecords(root).find((r) => r.sessionId === sid);
+  return mine ? mine.chat : null;
+}
+
+// Scope is what a chat declares it owns. The Aug 26 coordination burst had
+// sessions declaring this by hand in chat messages; recording it makes it
+// answerable without asking.
+function setScope(root, chatName, { epic = null, labels = [], paths = [] } = {}) {
+  const rec = readRecord(root, chatName);
+  if (!rec) throw new Error(`setScope: no chat record for "${chatName}"`);
+  rec.scope = { epic, labels, paths };
+  writeRecord(root, rec);
+  return rec;
+}
+
+function parseArgs(argv) {
+  const args = { root: '.', mode: null, chat: null, sessionId: null, name: null, workItem: null, branch: null, repo: null };
+  const rest = argv.slice(2);
+  for (let i = 0; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--root') { args.root = rest[++i]; continue; }
+    if (a === '--list') { args.mode = 'list'; continue; }
+    if (a === '--read') { args.mode = 'read'; args.chat = rest[++i]; continue; }
+    if (a === '--reconcile') { args.mode = 'reconcile'; continue; }
+    if (a === '--whoami') { args.mode = 'whoami'; continue; }
+    if (a === '--add-task') { args.mode = 'add-task'; continue; }
+    if (a === '--remove-task') { args.mode = 'remove-task'; continue; }
+    if (a === '--chat') { args.chat = rest[++i]; continue; }
+    if (a === '--work-item') { args.workItem = rest[++i]; continue; }
+    if (a === '--branch') { args.branch = rest[++i]; continue; }
+    if (a === '--repo') { args.repo = rest[++i]; continue; }
+    if (a === '--session-id') { args.sessionId = rest[++i]; continue; }
+    if (a === '--name') { args.name = rest[++i]; continue; }
+    throw new Error(`unknown argument: ${a}`);
+  }
+  if (!args.mode) throw new Error('one of --list, --read <chat>, --reconcile, --whoami is required');
+  if (args.mode === 'reconcile' && (!args.sessionId || !args.name)) {
+    throw new Error('--reconcile requires --session-id and --name');
+  }
+  if (args.mode === 'add-task' && (!args.chat || !args.workItem || !args.branch)) {
+    throw new Error('--add-task requires --chat, --work-item and --branch');
+  }
+  if (args.mode === 'remove-task' && (!args.chat || !args.workItem)) {
+    throw new Error('--remove-task requires --chat and --work-item');
+  }
+  return args;
+}
+
+function main() {
+  const args = parseArgs(process.argv);
+  if (args.mode === 'whoami') {
+    // A bare name, not JSON: the caller wants something to put on a command
+    // line. No match prints nothing and exits 1 — the caller decides what
+    // an unidentified chat means.
+    const name = whoami(args.root);
+    if (name === null) process.exit(1);
+    process.stdout.write(`${name}\n`);
+    return;
+  }
+  let out;
+  if (args.mode === 'list') out = listRecords(args.root);
+  else if (args.mode === 'read') out = readRecord(args.root, args.chat);
+  else if (args.mode === 'add-task') {
+    out = addTask(args.root, args.chat, { workItem: args.workItem, branch: args.branch, repo: args.repo });
+  } else if (args.mode === 'remove-task') {
+    out = removeTask(args.root, args.chat, { workItem: args.workItem, repo: args.repo });
+  } else out = reconcile(args.root, { sessionId: args.sessionId, name: args.name });
+  process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+}
+
+if (isMainModule(import.meta.url)) {
+  try {
+    main();
+  } catch (err) {
+    process.stderr.write(`chat-record: ${err.message}\n`);
+    process.exit(2);
+  }
+}
+
+export {
+  recordPath, drawerPath, emptyRecord, readRecord, writeRecord,
+  listRecords, reconcile, parseArgs, readSessionRegistry, resolveChatName,
+  addTask, removeTask, setScope, whoami, CHATS_DIR,
+};