@ulysses-ai/create-workspace 0.21.0-beta.0 → 0.23.0-beta.0

package/template/_claude/scripts/task-pr.mjs

@@ -16,14 +16,15 @@
 //
 // Usage:
 //   node task-pr.mjs --create --root <launcher> --branch <branch>
-//                    [--work-item gh:N] [--chat <name> | --repo <r> ...]
+//                    [--work-item gh:N|gl:N] [--chat <name> | --repo <r> ...]
 //                    --body-file <forge-repo>=<path> ... [--out <file>]
 //                    [--force-with-lease]
 //   node task-pr.mjs --merge --root <launcher> --prs <json-from-create>
-//                    [--work-item gh:N]
+//                    [--work-item gh:N|gl:N]
 //
 // Every repo of the task resolves to a merge mode (mergeModeFor below):
-// "forge" — its origin is a forge-hosted owner/name — or "local" — no
+// "forge" — its origin is forge-hosted (github.com, gitlab.com, or the
+// configured self-managed GitLab host) — or "local" — no
 // origin at all, or an explicit "local" override in workspace.json
 // (repos.{repo}.merge / workspace.merge), the escape hatch for a clone
 // whose origin is a third-party upstream nobody here may push to. An
@@ -39,7 +40,9 @@
 // body file is required per forge repo alone; one given for a local repo
 // is ignored). The PR title is the linked issue's title when --work-item
 // is given, else the branch's first commit subject; the body is the
-// repo's body file with `Closes <ref>` appended. Prints
+// repo's body file with a closing reference appended — `Closes <ref>`
+// when the tracker's forge matches the PR's, else the issue's URL (a
+// GitHub `owner/repo#N` reference cannot resolve on GitLab). Prints
 // `{ prs, empty, pushed }` — prs holds forge entries (mode "forge") and
 // local entries (mode "local") alike, every entry carrying its commit
 // count — and, with --out, writes the same JSON to a file — a mid-run
@@ -77,7 +80,7 @@ import { resolve, dirname } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { taskWorktreePath, defaultBranchFor } from './task-worktree.mjs';
-import { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, mergeModeFor } from './merge-mode.mjs';
+import { WORKSPACE_REPO, repoDirFor, readWorkspace, parseForgeRemote, forgeHosts, perRepoForge, mergeModeFor } from './merge-mode.mjs';
 import { readRecord } from './chat-record.mjs';
 import { createForge } from './forges/interface.mjs';
 import { createTracker } from './trackers/interface.mjs';
@@ -97,6 +100,33 @@ function assertForgeEnabled(ws) {
   }
 }
 
+// perRepoForge (from merge-mode.mjs, re-exported below) builds each repo's
+// forge config; see its definition there for why the origin wins over the
+// workspace-level type.
+
+// Which forge an issues adapter's references resolve on — `owner/repo#N`
+// from github-issues only closes on GitHub, `group/sub#N` from
+// gitlab-issues only on GitLab.
+const TRACKER_FORGE = { 'github-issues': 'github', 'gitlab-issues': 'gitlab' };
+
+// The closing line for a PR body. Same forge as the tracker: the native
+// reference (issueRef). Cross-forge — a GitHub tracker's issue referenced
+// from a GitLab MR, or the reverse — cannot use it, since the target forge
+// cannot resolve the reference; the line carries the issue's URL instead.
+// As `Closes {url}` when the tracker mints canonical URLs (issueUrl —
+// both forges close issues referenced by full URL); otherwise as a bare
+// `Refs {url}` on the URL getIssue already returned, which references the
+// issue without claiming close semantics the target forge may not honor.
+function closingLineFor(tracker, issue, workItem, target, trackerConfig) {
+  const ref = tracker.issueRef(workItem, { fromRepo: `${target.owner}/${target.name}` });
+  const trackerForge = trackerConfig?.type ? TRACKER_FORGE[trackerConfig.type] : undefined;
+  if (!trackerForge || !target.forge || trackerForge === target.forge) {
+    return `Closes ${ref}`;
+  }
+  if (typeof tracker.issueUrl === 'function') return `Closes ${tracker.issueUrl(workItem)}`;
+  return issue?.url ? `Refs ${issue.url}` : `Closes ${ref}`;
+}
+
 // Branch names become refs, refspecs, and (via the slug) paths; git's own
 // format check is the authority, and its --branch variant also rejects
 // names a later git call could mistake for an option. It needs no
@@ -236,7 +266,7 @@ async function createPrs(args, deps) {
   // still complete with forge operations disabled.
   if (forgeActive.length > 0) assertForgeEnabled(ws);
   for (const t of forgeActive) {
-    Object.assign(t, parseForgeRemote(gitOut(deps.gitFn, t.worktree, ['remote', 'get-url', 'origin'])));
+    Object.assign(t, parseForgeRemote(gitOut(deps.gitFn, t.worktree, ['remote', 'get-url', 'origin']), { hosts: forgeHosts(ws) }));
   }
   for (const t of forgeActive) {
     const bodyFile = args.bodyFiles.get(t.repo);
@@ -249,11 +279,12 @@ async function createPrs(args, deps) {
   }
 
   let issueTitle = null;
-  let issueRefs = null;
+  let closingLines = null;
   if (args.workItem && ws.workspace?.tracker) {
     const tracker = deps.trackerFactory(ws.workspace.tracker);
-    issueTitle = (await tracker.getIssue(args.workItem)).title;
-    issueRefs = new Map(forgeActive.map((t) => [t.repo, tracker.issueRef(args.workItem, { fromRepo: `${t.owner}/${t.name}` })]));
+    const issue = await tracker.getIssue(args.workItem);
+    issueTitle = issue.title;
+    closingLines = new Map(forgeActive.map((t) => [t.repo, closingLineFor(tracker, issue, args.workItem, t, ws.workspace.tracker)]));
   }
 
   // Local entries are recorded up front, before anything can fail: they are
@@ -273,7 +304,7 @@ async function createPrs(args, deps) {
     }
 
     for (const t of forgeActive) {
-      const forge = deps.forgeFactory({ ...(ws.workspace?.forge ?? {}), repo: `${t.owner}/${t.name}` });
+      const forge = deps.forgeFactory(perRepoForge(ws, t));
       // Idempotency: a re-run must not open a second PR for a branch that
       // already has one open against the same base. Reuse it as-is —
       // re-titling or re-bodying an existing PR is a decision, not a
@@ -282,10 +313,11 @@ async function createPrs(args, deps) {
         .find((p) => p.headRefName === args.branch && p.baseRefName === t.defaultBranch);
       const title = issueTitle ?? firstCommitSubject(deps.gitFn, t, args.branch);
       let body = readFileSync(args.bodyFiles.get(t.repo), 'utf8').replace(/\s*$/, '');
-      if (issueRefs) body = `${body}\n\nCloses ${issueRefs.get(t.repo)}\n`;
+      if (closingLines) body = `${body}\n\n${closingLines.get(t.repo)}\n`;
       const pr = existing ?? await forge.prCreate({ title, body, head: args.branch, base: t.defaultBranch });
       prs.push({
         repo: t.repo, mode: 'forge', owner: t.owner, name: t.name,
+        forge: t.forge, host: t.host,
         number: pr.number, id: pr.id, url: pr.url, isWorkspace: t.isWorkspace, commits: t.commits,
       });
     }
@@ -375,7 +407,14 @@ async function mergePrs(args, deps) {
     }
   }
   if (prs.some((p) => modeOf(p) === 'forge')) assertForgeEnabled(ws);
-  const forgeFor = (p) => deps.forgeFactory({ ...(ws.workspace?.forge ?? {}), repo: `${p.owner}/${p.name}` });
+  // Entries carry their repo's forge and host since GitLab support landed;
+  // older files predate the fields and fall back to the workspace block —
+  // the GitHub default those runs were built under.
+  const forgeFor = (p) => deps.forgeFactory({
+    ...(ws.workspace?.forge ?? {}),
+    ...(p.forge ? { type: p.forge, host: p.host } : {}),
+    repo: `${p.owner}/${p.name}`,
+  });
 
   // State first, so a re-run knows what an earlier run already finished.
   // A PR the forge reports MERGED is done; anything else is offered to
@@ -552,4 +591,4 @@ if (isMainModule(import.meta.url)) {
 }
 
 export { run, parseArgs };
-export { parseForgeRemote, mergeModeFor } from './merge-mode.mjs';
+export { parseForgeRemote, mergeModeFor, perRepoForge, forgeConfigForRepo } from './merge-mode.mjs';

package/template/_claude/scripts/task-worktree.mjs

@@ -23,19 +23,28 @@
 // chat name it also consults the chat record, which is the only place
 // open tasks are listed. /complete-work uses that to pick its flow.
 //
+// Long-lived lane chats sit at the launcher across BOTH lifecycles, so
+// detection also matches the chat's session id against each old session's
+// chatSessions frontmatter — a chat that drove a work-sessions/{name}/
+// session by path is findable from the launcher too (gh:188). The id comes
+// from --session-id, from the named chat record's sessionId, or from
+// $CLAUDE_CODE_SESSION_ID, in that order. Tasks AND sessions at once
+// report model "mixed" and let the operator pick.
+//
 // Usage:
 //   node task-worktree.mjs --root <dir> --create --repo <r> --branch <b> [--base <ref>]
 //   node task-worktree.mjs --root <dir> --remove --repo <r> --branch <b> [--force] [--delete-branch]
-//   node task-worktree.mjs --root <dir> --detect [--cwd <dir>] [--chat <name>]
+//   node task-worktree.mjs --root <dir> --detect [--cwd <dir>] [--chat <name>] [--session-id <id>]
 
 import {
-  readFileSync, writeFileSync, existsSync, mkdirSync, statSync,
+  readFileSync, writeFileSync, existsSync, mkdirSync, statSync, readdirSync,
 } from 'node:fs';
 import { realpathSync } from 'node:fs';
 import { join, resolve, relative, sep, isAbsolute, basename, dirname } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { readRecord } from './chat-record.mjs';
+import { readSessionFields } from '../lib/session-frontmatter.mjs';
 import { WORKSPACE_REPO, repoDirFor, mergeModeFor } from './merge-mode.mjs';
 
 function isMainModule(metaUrl) {
@@ -192,9 +201,11 @@ function ensureWorkspaceExcluded(gitFn, rootDir) {
  * Create (or return) the task worktree for {branch} in {repo}.
  *
  * Idempotent: a worktree already at the path on the same branch is a
- * success — /start-work is not guaranteed to run exactly once per task. A
- * path held by anything else is a collision and refuses rather than
- * guessing. Three creation cases, in order:
+ * success — /start-work is not guaranteed to run exactly once per task,
+ * and adopting another chat's task re-runs --create over the owner's
+ * existing worktree, which must be reused (created: false), never
+ * duplicated or failed. A path held by anything else is a collision and
+ * refuses rather than guessing. Three creation cases, in order:
  *   - the local branch exists (a prior remove kept it) → check it out,
  *     keeping its commits;
  *   - only refs/remotes/origin/{branch} exists → the task was started on
@@ -382,6 +393,58 @@ function matchingTasks(rootDir, chat, branch) {
   return tasks.length > 0 ? tasks : null;
 }
 
+// The sessions a chat id has driven, from each tracker's chatSessions. A
+// lane chat at the launcher works a session by path, so cwd can never say
+// which — the id the SessionStart hook registered is the only link. All
+// matches come back (a chat can hop across sessions over days); the caller
+// asks the operator when there is more than one. Archived sessions sit at
+// work-sessions/.archived/{name}/workspace/ — one level too deep for this
+// scan, so they never surface.
+function matchingSessions(rootReal, sessionId) {
+  if (!sessionId) return null;
+  const sessionsDir = sessionsDirFor(rootReal);
+  let names;
+  try {
+    names = readdirSync(sessionsDir).sort();
+  } catch {
+    return null; // no sessions dir — nothing to match
+  }
+  const out = [];
+  for (const name of names) {
+    const tracker = join(sessionsDir, name, 'workspace', 'session.md');
+    if (!existsSync(tracker)) continue;
+    let fields;
+    try {
+      fields = readSessionFields(tracker);
+    } catch {
+      continue; // an unparseable tracker is evidence about the tracker, not this chat
+    }
+    const chats = Array.isArray(fields.chatSessions) ? fields.chatSessions : [];
+    if (!chats.some((c) => c && c.id === sessionId)) continue;
+    out.push({
+      name,
+      branch: typeof fields.branch === 'string' ? fields.branch : null,
+      workItem: typeof fields.workItem === 'string' ? fields.workItem : null,
+      status: typeof fields.status === 'string' ? fields.status : null,
+    });
+  }
+  return out.length > 0 ? out : null;
+}
+
+// Which session id detection matches sessions by: an explicit argument
+// beats the named chat record's sessionId (the record IS this chat's id,
+// keyed stably where a name is renameable), which beats the ambient
+// $CLAUDE_CODE_SESSION_ID — the hook's id, present even when the hook's
+// `Chat record:` line was compacted away.
+function resolveSessionId(rootDir, chat, sessionId, env) {
+  if (sessionId) return sessionId;
+  if (chat) {
+    const rec = readRecord(rootDir, chat);
+    if (rec && rec.sessionId) return rec.sessionId;
+  }
+  return (env && env.CLAUDE_CODE_SESSION_ID) || null;
+}
+
 // One task worktree's detect payload, or null when {path} does not really
 // hold a task: a stale plain directory under .claude/worktrees/ would
 // otherwise detect through cwd and resolve to the repo around it — for the
@@ -408,10 +471,12 @@ function taskWorktreeInfo(gitFn, rootReal, repo, path, chat) {
  * Tell a skill which lifecycle the current directory is under, in order:
  * session (cwd in the old model's tree), task (cwd in a task worktree,
  * enriched with the chat's matching tasks when {chat} is given), then —
- * because task chats run at the launcher, where cwd is just the root —
- * task again if the named chat's record has open tasks. Else none.
+ * because lane chats run at the launcher, where cwd is just the root —
+ * task if the named chat's record has open tasks, session if the chat's
+ * session id appears in any tracker's chatSessions, "mixed" when both.
+ * Else none.
  */
-function detectWorkModel(cwd, root, { chat = null, gitFn = spawnSync } = {}) {
+function detectWorkModel(cwd, root, { chat = null, sessionId = null, gitFn = spawnSync, env = process.env } = {}) {
   const rootReal = realPath(resolve(root));
   const cwdReal = realPath(resolve(cwd));
 
@@ -441,7 +506,10 @@ function detectWorkModel(cwd, root, { chat = null, gitFn = spawnSync } = {}) {
   }
 
   const tasks = matchingTasks(rootReal, chat, null);
+  const sessions = matchingSessions(rootReal, resolveSessionId(rootReal, chat, sessionId, env));
+  if (tasks && sessions) return { model: 'mixed', tasks, sessions };
   if (tasks) return { model: 'task', source: 'chat-record', tasks };
+  if (sessions) return { model: 'session', source: 'chat-sessions', sessions };
 
   return { model: 'none' };
 }
@@ -454,6 +522,7 @@ const VALUE_FLAGS = new Map([
   ['--base', 'base'],
   ['--cwd', 'cwd'],
   ['--chat', 'chat'],
+  ['--session-id', 'sessionId'],
 ]);
 
 // A repo name becomes a path segment under repos/ — one segment only, no
@@ -468,7 +537,7 @@ function isRepoSegment(repo) {
 }
 
 function parseArgs(argv) {
-  const args = { root: '.', mode: null, repo: null, branch: null, base: null, cwd: null, chat: null, force: false, deleteBranch: false };
+  const args = { root: '.', mode: null, repo: null, branch: null, base: null, cwd: null, chat: null, sessionId: null, force: false, deleteBranch: false };
   const rest = argv.slice(2);
   for (let i = 0; i < rest.length; i += 1) {
     const a = rest[i];
@@ -513,7 +582,7 @@ function main() {
   } else if (args.mode === 'remove') {
     out = removeTaskWorktree(args.root, { repo: args.repo, branch: args.branch, force: args.force, deleteBranch: args.deleteBranch });
   } else {
-    out = detectWorkModel(args.cwd || process.cwd(), args.root, { chat: args.chat });
+    out = detectWorkModel(args.cwd || process.cwd(), args.root, { chat: args.chat, sessionId: args.sessionId });
   }
   process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
 }

package/template/_claude/scripts/template-baseline.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+// Template baseline: the sha256 of every verbatim-installed file the template
+// last shipped, recorded at <root>/.claude/.template-baseline.json. It is the
+// third input of /workspace-update's three-way classification (workspace vs
+// payload vs baseline), so a file the template changed since the installed
+// version reads as an update to apply in batch — not a local edit to negotiate
+// file by file (gh:183).
+//
+// Shape:
+//   { "templateVersion": "0.21.0",
+//     "files": { ".claude/skills/workspace-update/SKILL.md": "<sha256>", … } }
+// Keys are root-relative posix paths covering the verbatim-installed roots
+// (.claude/**, .mcp.json, .claudeignore). The file is committed with the
+// workspace — every machine that pulls gets the same template files, so it
+// gets the same baseline.
+//
+// Written by `--init` scaffolding (lib/init.mjs), by /workspace-init once the
+// remaining components are installed, and at the end of every /workspace-update
+// (classify-update.mjs --write-baseline). Interactive scaffolding writes it
+// from the template tree (lib/scaffold.mjs).
+//
+// The rule every entry follows: record the hash of the payload's content —
+// what the template last shipped — never the workspace's on-disk bytes. A
+// file the user kept despite a template change therefore keeps the PAYLOAD
+// hash: the next update sees workspace ≠ baseline with payload == baseline
+// and reports the file as a purely local edit (informational, not re-asked
+// per file) until the template touches it again, and a deliberate divergence
+// is never silently adopted as the new baseline. One exception: an unapplied
+// update — the workspace still holds the OLD baseline content while the
+// payload ships something new (the user declined the `updated` batch) — keeps
+// the old entry, so the file re-presents as `updated` next time instead of
+// being filed away as a local edit. The invariant that matters either way: a
+// file the user never touched (workspace == baseline) is never reported as a
+// local edit.
+//
+// All hashes are CRLF-normalized for text files (see hashBytes): a Windows
+// autocrlf checkout stores CRLF where the payload carries LF, and byte-exact
+// hashing would read every such file as locally modified. Files containing
+// NUL bytes hash byte-exact.
+//
+// Not covered: *.test.mjs (the tarball never ships them; a workspace's test
+// files came from a dev checkout and age independently — classify-update
+// reports them as staleTests instead), machine-local files
+// (.claude/settings.local.json, .claude/.active-session.json), and anything
+// under .claude/worktrees/.
+
+import { createHash } from 'node:crypto';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const BASELINE_PATH = '.claude/.template-baseline.json';
+
+// Where --upgrade stages a RECONSTRUCTED baseline (built from the installed
+// version's npm tarball) inside the payload. It never lands in the launcher:
+// with a remote, /workspace-update classifies inside a task worktree that
+// cannot see launcher-only files, and an untracked launcher baseline would
+// also dirty the launcher against the incoming PR. The payload travels to
+// the worktree by absolute path, so the baseline rides along.
+export const RECONSTRUCTED_BASELINE_NAME = '.template-baseline.reconstructed.json';
+
+// [source name, installed name] pairs for the verbatim-installed roots. The
+// staged payload carries the live names; the template tree stores .claude/ and
+// .mcp.json under the inert names _claude/ and _mcp.json, so scaffold passes
+// the inert pairs.
+export const LIVE_PAIRS = [
+  ['.claude', '.claude'],
+  ['.mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+export const INERT_PAIRS = [
+  ['_claude', '.claude'],
+  ['_mcp.json', '.mcp.json'],
+  ['.claudeignore', '.claudeignore'],
+];
+
+// Machine-local or per-workspace files that never belong in the baseline.
+const OWNED_PATHS = new Set([
+  '.claude/settings.local.json',
+  '.claude/.active-session.json',
+  BASELINE_PATH,
+]);
+
+// Entire nested worktrees live under .claude/worktrees/ — never walked.
+const SKIP_DIRS = new Set(['worktrees']);
+
+/**
+ * The content hash used by the baseline and by classification: sha256 with
+ * CRLF normalized to LF for text files, byte-exact for binary (anything
+ * containing a NUL byte — git's own text/binary heuristic). Both the payload
+ * and the workspace side hash through this, so a git autocrlf checkout that
+ * stores CRLF where the payload ships LF classifies as identical instead of
+ * reading every file as locally modified.
+ */
+export function hashBytes(bytes) {
+  let body = bytes;
+  if (!bytes.includes(0)) {
+    // latin1 round-trips bytes 1:1 — safe on text that isn't valid UTF-8 too.
+    body = Buffer.from(bytes.toString('latin1').replace(/\r\n/g, '\n'), 'latin1');
+  }
+  return createHash('sha256').update(body).digest('hex');
+}
+
+function* walkFiles(dir, prefix = '') {
+  let entries;
+  try {
+    entries = readdirSync(dir).sort();
+  } catch {
+    return;
+  }
+  for (const name of entries) {
+    if (prefix === '.claude' && SKIP_DIRS.has(name)) continue;
+    const rel = prefix ? `${prefix}/${name}` : name;
+    const full = join(dir, name);
+    let st;
+    try { st = statSync(full); } catch { continue; }
+    if (st.isDirectory()) yield* walkFiles(full, rel);
+    else if (st.isFile()) yield rel;
+  }
+}
+
+/**
+ * Read a baseline JSON file at an explicit path. Returns
+ * { templateVersion, files, reconstructed } or null when absent or
+ * unparseable — a corrupt baseline is treated exactly like a missing one
+ * (gh:186) so classification falls back to the two-way behavior rather than
+ * failing the update, and reconstruction is not blocked by a broken file.
+ */
+export function readBaselineFile(path) {
+  if (!existsSync(path)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object' || parsed.files === null) {
+      return null;
+    }
+    return {
+      templateVersion: typeof parsed.templateVersion === 'string' ? parsed.templateVersion : null,
+      files: parsed.files,
+      reconstructed: parsed.reconstructed === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read the baseline at <root>/.claude/.template-baseline.json. Returns the
+ * parsed baseline or null when absent (workspaces older than the baseline's
+ * introduction) or unparseable.
+ */
+export function readBaseline(root) {
+  return readBaselineFile(join(resolve(root), BASELINE_PATH));
+}
+
+/**
+ * Build a baseline from a template source directory (a staged payload with
+ * live names, or the template tree via INERT_PAIRS). `version` overrides the
+ * payload manifest's templateVersion — pass it when the source has no
+ * .manifest.json (the template tree).
+ */
+export function buildBaseline(sourceDir, { pairs = LIVE_PAIRS, version = null } = {}) {
+  const absSource = resolve(sourceDir);
+  const files = {};
+  for (const [sourceName, installedName] of pairs) {
+    const src = join(absSource, sourceName);
+    if (!existsSync(src)) continue;
+    let st;
+    try { st = statSync(src); } catch { continue; }
+    if (st.isFile()) {
+      if (!OWNED_PATHS.has(installedName) && !installedName.endsWith('.test.mjs')) {
+        files[installedName] = hashBytes(readFileSync(src));
+      }
+      continue;
+    }
+    for (const rel of walkFiles(src, installedName)) {
+      if (OWNED_PATHS.has(rel) || rel.endsWith('.test.mjs')) continue;
+      files[rel] = hashBytes(readFileSync(join(absSource, sourceName, rel.slice(installedName.length + 1))));
+    }
+  }
+  let templateVersion = version;
+  if (templateVersion === null) {
+    try {
+      const manifest = JSON.parse(readFileSync(join(absSource, '.manifest.json'), 'utf8'));
+      if (typeof manifest.templateVersion === 'string') templateVersion = manifest.templateVersion;
+    } catch {
+      // No manifest (or unreadable) — caller should pass `version`.
+    }
+  }
+  return { templateVersion, files: Object.fromEntries(Object.keys(files).sort().map((k) => [k, files[k]])) };
+}
+
+/**
+ * Write the baseline for the workspace at `root`. Returns the written object.
+ *
+ * Refuses to write an empty baseline: a missing source directory or one that
+ * yields zero verbatim files throws rather than clobbering an existing good
+ * baseline with `{files:{}}` (which would make the next update classify every
+ * template change as a local edit).
+ *
+ * Before writing, entries carried over from the previous baseline are kept as
+ * they were for unapplied updates: a file whose workspace content still
+ * matches the old baseline while the payload ships something new (a declined
+ * `updated` batch) keeps the OLD entry, so the next update still offers the
+ * change instead of filing the file away as a local edit. The previous
+ * baseline defaults to <root>/.claude/.template-baseline.json; pass
+ * opts.previous to override (the worktree flow reads the payload's
+ * reconstructed baseline when the root has none of its own).
+ */
+export function writeBaseline(root, sourceDir, opts = {}) {
+  const absRoot = resolve(root);
+  const baseline = buildBaseline(sourceDir, opts);
+  if (Object.keys(baseline.files).length === 0) {
+    throw new Error(
+      `No verbatim template files found under ${resolve(sourceDir)} — refusing to write an empty baseline`,
+    );
+  }
+  const previous = 'previous' in opts ? opts.previous : readBaseline(absRoot);
+  if (previous) {
+    for (const rel of Object.keys(baseline.files)) {
+      const oldHash = previous.files[rel];
+      if (typeof oldHash !== 'string' || oldHash === baseline.files[rel]) continue;
+      const installed = join(absRoot, rel);
+      if (existsSync(installed) && hashBytes(readFileSync(installed)) === oldHash) {
+        // Unapplied update: the workspace never took the payload's change.
+        baseline.files[rel] = oldHash;
+      }
+    }
+  }
+  const dest = join(absRoot, BASELINE_PATH);
+  mkdirSync(dirname(dest), { recursive: true });
+  writeFileSync(dest, JSON.stringify(baseline, null, 2) + '\n');
+  return baseline;
+}