@1agh/maude 0.48.0 → 0.49.0

package/apps/studio/sync/autocommit.ts

@@ -0,0 +1,299 @@
+// Autosave → append-only git commits — Cloud Phase 3 Task 1.
+//
+// On a laptop, autosave writing a file IS the save: the developer's own git is
+// the history, and they commit when they mean to. In a workspace cell there is
+// no developer at the keyboard, so an unwritten history means the only record
+// of a design is its current bytes — one bad sync away from unrecoverable.
+//
+// So the cell commits. Three rules make that safe rather than merely noisy:
+//
+//   1. APPEND-ONLY. `git add` + `git commit`, ever. No amend, no rebase, no
+//      reset, no `checkout --` over a dirty tree, and NEVER a force-push. The
+//      history is allowed to be ugly; it is not allowed to lose a state that
+//      once existed.
+//   2. AUTHORSHIP IS THE EDITING HUMAN. git separates author from committer
+//      precisely for this: the author is the person whose edit this was (from
+//      presence), the committer is the workspace bot. `git blame` then answers
+//      "who designed this" instead of "the server did", which is the whole
+//      reason to keep history at all.
+//   3. QUIESCENCE, NOT KEYSTROKES. Commits fire after edits stop, so a typing
+//      session is one commit rather than four hundred.
+//
+// The disk write has ALREADY happened by the time anything here runs. A git
+// failure therefore never loses work — it leaves the change uncommitted and
+// retries on the next quiescence. That ordering is deliberate: making the
+// commit a precondition of the save would turn a transient git error into
+// data loss, which is precisely backwards.
+
+import path from 'node:path';
+
+/** How long the tree must be quiet before a commit fires. */
+const DEFAULT_DEBOUNCE_MS = 3000;
+
+export interface GitRunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Injected so tests drive a real repo and callers can swap the runner. */
+export type GitRunner = (args: string[], opts: { cwd: string }) => Promise<GitRunResult>;
+
+export interface EditAttribution {
+  /** Display name from presence, e.g. "Alice Novak". */
+  name: string;
+  /** Address from presence, or a synthesized stable one. */
+  email: string;
+}
+
+export interface AutoCommitOptions {
+  repoRoot: string;
+  run: GitRunner;
+  /** Quiescence window. */
+  debounceMs?: number;
+  /** Committer identity — the machine, never the human. */
+  bot?: EditAttribution;
+  log?: Pick<Console, 'warn' | 'error' | 'log'>;
+}
+
+export interface AutoCommit {
+  /**
+   * Record that `relPath` changed, attributed to `who`. Repeated calls within
+   * the debounce window coalesce into one commit.
+   */
+  note(relPath: string, who?: EditAttribution | null): void;
+  /** Force the pending commit now (branch switch, shutdown). */
+  flush(): Promise<CommitOutcome | null>;
+  /** Pending paths, for tests + status surfaces. */
+  pending(): string[];
+  stop(): void;
+}
+
+export type CommitOutcome =
+  | { ok: true; sha: string; files: string[]; author: EditAttribution }
+  | { ok: false; reason: 'nothing-to-commit' | 'git-failed'; detail?: string; files: string[] };
+
+const DEFAULT_BOT: EditAttribution = {
+  name: 'Maude Workspace',
+  email: 'workspace@maude.local',
+};
+
+/**
+ * Attribution for an edit whose author we don't know.
+ *
+ * Deliberately NOT the bot: attributing an anonymous human's work to the server
+ * makes `git blame` lie in a way that is hard to notice later. "Unknown" is
+ * honest, and it is visibly wrong in a way that prompts a fix.
+ */
+export const UNKNOWN_AUTHOR: EditAttribution = {
+  name: 'Unknown editor',
+  email: 'unknown@maude.local',
+};
+
+/**
+ * Sanitize a presence-supplied identity before it reaches a git argument.
+ *
+ * Presence comes from peers over the hub, which is semi-trusted (DDR-054): a
+ * name is attacker-influenceable text. Newlines are the specific hazard —
+ * `git commit --author` takes `Name <email>`, and an embedded newline could
+ * forge trailer lines in the commit message. Everything is passed as argv (no
+ * shell), so this is about the git format, not shell quoting.
+ */
+export function sanitizeAttribution(who: EditAttribution | null | undefined): EditAttribution {
+  if (!who) return UNKNOWN_AUTHOR;
+  const clean = (s: string, fallback: string) => {
+    const out = String(s ?? '')
+      // biome-ignore lint/suspicious/noControlCharactersInRegex: stripping control chars is the point.
+      .replace(/[\s\u0000-\u001f\u007f-\u009f]+/g, ' ')
+      .replace(/[<>]/g, '')
+      .trim()
+      .slice(0, 96);
+    return out || fallback;
+  };
+  return {
+    name: clean(who.name, UNKNOWN_AUTHOR.name),
+    email: clean(who.email, UNKNOWN_AUTHOR.email),
+  };
+}
+
+/** `Name <email>` as git's `--author` wants it. */
+export function formatAuthor(who: EditAttribution): string {
+  const s = sanitizeAttribution(who);
+  return `${s.name} <${s.email}>`;
+}
+
+/**
+ * Commit subject. Names WHAT changed rather than "autosave", because a history
+ * of four hundred identical subjects is the same as no history.
+ */
+export function commitMessage(files: string[], who: EditAttribution): string {
+  // Strip from the FIRST dot, not the last: `Screen.tsx` and `Screen.meta.json`
+  // are one canvas, and counting them as two would make every commit subject
+  // overstate what changed.
+  const canvases = [...new Set(files.map((f) => path.basename(f).replace(/\..*$/, '')))].sort();
+  const subject =
+    canvases.length === 1
+      ? `design: update ${canvases[0]}`
+      : `design: update ${canvases.length} canvases`;
+  const body = [
+    '',
+    canvases.length > 1 ? canvases.map((c) => `- ${c}`).join('\n') : '',
+    '',
+    `Edited by ${who.name} <${who.email}> via the Maude workspace.`,
+    'Autosaved — append-only; this history is never rewritten.',
+  ]
+    .filter((line, i, all) => !(line === '' && all[i - 1] === ''))
+    .join('\n');
+  return `${subject}\n${body}`;
+}
+
+export function createAutoCommit(opts: AutoCommitOptions): AutoCommit {
+  const {
+    repoRoot,
+    run,
+    debounceMs = DEFAULT_DEBOUNCE_MS,
+    bot = DEFAULT_BOT,
+    log = console,
+  } = opts;
+
+  const touched = new Set<string>();
+  let author: EditAttribution | null = null;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  let inFlight: Promise<CommitOutcome | null> | null = null;
+  let stopped = false;
+
+  function note(relPath: string, who?: EditAttribution | null): void {
+    if (stopped) return;
+    touched.add(relPath);
+    // Last writer wins for attribution. A commit that coalesced two people's
+    // edits can only name one author; the message body names them, and the
+    // alternative (splitting per author) would fight the quiescence batching
+    // that keeps this history readable.
+    if (who) author = who;
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      void flush();
+    }, debounceMs);
+  }
+
+  async function flush(): Promise<CommitOutcome | null> {
+    if (inFlight) return inFlight;
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (touched.size === 0) return null;
+
+    const files = [...touched].sort();
+    const who = sanitizeAttribution(author);
+    touched.clear();
+    author = null;
+
+    inFlight = (async (): Promise<CommitOutcome> => {
+      try {
+        // Stage ONLY what changed. `git add -A` in a workspace would sweep in
+        // whatever else is in the tree — including files a future feature drops
+        // there — and the cell must never commit something it wasn't told about.
+        const add = await run(['add', '--', ...files], { cwd: repoRoot });
+        if (add.code !== 0) {
+          log.warn?.(`[autocommit] git add failed: ${add.stderr.trim()}`);
+          return { ok: false, reason: 'git-failed', detail: add.stderr.trim(), files };
+        }
+
+        // Nothing staged ⇒ the write was a no-op (an echo, or identical bytes).
+        // Not an error, and committing an empty change would be noise.
+        const staged = await run(['diff', '--cached', '--name-only'], { cwd: repoRoot });
+        if (staged.code === 0 && staged.stdout.trim() === '') {
+          return { ok: false, reason: 'nothing-to-commit', files };
+        }
+
+        const commit = await run(
+          [
+            '-c',
+            `user.name=${bot.name}`,
+            '-c',
+            `user.email=${bot.email}`,
+            'commit',
+            '--author',
+            formatAuthor(who),
+            '--only',
+            '--message',
+            commitMessage(files, who),
+            '--',
+            ...files,
+          ],
+          { cwd: repoRoot }
+        );
+        if (commit.code !== 0) {
+          log.warn?.(`[autocommit] git commit failed: ${commit.stderr.trim()}`);
+          // The bytes are on disk. Re-queue so the next quiescence retries
+          // rather than silently dropping the change from history.
+          for (const f of files) touched.add(f);
+          return { ok: false, reason: 'git-failed', detail: commit.stderr.trim(), files };
+        }
+
+        const head = await run(['rev-parse', 'HEAD'], { cwd: repoRoot });
+        const sha = head.stdout.trim();
+        log.log?.(`[autocommit] ${sha.slice(0, 8)} ${files.length} file(s) by ${who.name}`);
+        return { ok: true, sha, files, author: who };
+      } finally {
+        inFlight = null;
+      }
+    })();
+
+    return inFlight;
+  }
+
+  return {
+    note,
+    flush,
+    pending: () => [...touched].sort(),
+    stop() {
+      stopped = true;
+      if (timer) {
+        clearTimeout(timer);
+        timer = null;
+      }
+    },
+  };
+}
+
+/**
+ * Push to a mirror remote, refusing anything that would rewrite it.
+ *
+ * A cell that force-pushes destroys work that exists only on the remote —
+ * exactly the hazard DDR-119 was written about, arriving from the other
+ * direction. On rejection the correct behaviour is to STOP and surface it, not
+ * to "resolve" it: a non-fast-forward means someone else's commits are there,
+ * and the cell has no way to know whether merging them is right.
+ */
+export async function pushMirror({
+  repoRoot,
+  run,
+  remote = 'origin',
+  branch,
+  log = console,
+}: {
+  repoRoot: string;
+  run: GitRunner;
+  remote?: string;
+  branch: string;
+  log?: Pick<Console, 'warn'>;
+}): Promise<{ ok: boolean; rejected: boolean; detail?: string }> {
+  // No --force, no --force-with-lease, no +refspec. If this ever needs one,
+  // that is a design conversation, not a flag.
+  const res = await run(['push', remote, `refs/heads/${branch}:refs/heads/${branch}`], {
+    cwd: repoRoot,
+  });
+  if (res.code === 0) return { ok: true, rejected: false };
+  const detail = `${res.stderr}\n${res.stdout}`.trim();
+  const rejected = /\brejected\b|non-fast-forward|fetch first/i.test(detail);
+  if (rejected) {
+    log.warn?.(
+      '[autocommit] mirror push REJECTED — someone else saved first. Stopping rather than ' +
+        'rewriting their work; the local history is intact and nothing was lost.'
+    );
+  }
+  return { ok: false, rejected, detail };
+}

package/apps/studio/sync/doc-name.ts

@@ -0,0 +1,228 @@
+// Document namespace, client side — `ws/<workspace-id>/<branch>/<slug>` (DDR-192 §5).
+//
+// ⚠ THE GRAMMAR IS MIRRORED in `apps/hub/src/doc-namespace.mjs` and the two are
+// pinned to each other by `test/sync-doc-name.test.ts`, which imports the hub's
+// implementation and asserts both agree over the same corpus. They are separate
+// files on purpose: the hub image installs frozen against its own bun.lock and
+// must not reach into apps/studio. Change one, change the other.
+//
+// WHAT IS NAMESPACED AND WHAT IS NOT: only the WIRE name changes. Every local
+// map — the provider registry, the sync agent, the projection, `_history/`,
+// `_comments/` — stays keyed by the flat slug. The namespace exists to keep two
+// projects (or two branches) from colliding INSIDE A HUB; on disk they already
+// live in different directories.
+
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+
+/** The prefix that marks a namespaced documentName. */
+export const DOC_NAMESPACE_PREFIX = 'ws';
+
+/** Max length of one path component (workspace id / branch / slug). */
+export const COMPONENT_MAX = 64;
+
+export interface DocNamespace {
+  workspaceId: string;
+  branch: string;
+  slug: string;
+}
+
+/**
+ * Normalize one path component into the namespace charset. `/` is the
+ * separator, so a git branch like `feature/foo` becomes `feature-foo`.
+ */
+export function sanitizeComponent(raw: string): string {
+  if (typeof raw !== 'string') return '';
+  return raw
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/-{2,}/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, COMPONENT_MAX)
+    .replace(/[-.]+$/g, '');
+}
+
+/** Build `ws/<workspace-id>/<branch>/<slug>`. Throws if a component is empty. */
+export function buildDocName({ workspaceId, branch, slug }: DocNamespace): string {
+  const w = sanitizeComponent(workspaceId);
+  const b = sanitizeComponent(branch);
+  const s = sanitizeComponent(slug);
+  if (!w) throw new Error('buildDocName: workspaceId is empty after normalization');
+  if (!b) throw new Error('buildDocName: branch is empty after normalization');
+  if (!s) throw new Error('buildDocName: slug is empty after normalization');
+  return `${DOC_NAMESPACE_PREFIX}/${w}/${b}/${s}`;
+}
+
+/** Parse a documentName; null means a legacy flat slug (expected, not an error). */
+export function parseDocName(name: string): DocNamespace | null {
+  if (typeof name !== 'string' || name.length === 0) return null;
+  const parts = name.split('/');
+  if (parts.length !== 4) return null;
+  const [prefix, workspaceId, branch, slug] = parts;
+  if (prefix !== DOC_NAMESPACE_PREFIX) return null;
+  if (!workspaceId || !branch || !slug) return null;
+  return { workspaceId, branch, slug };
+}
+
+/** True when `name` is a namespaced documentName. */
+export function isNamespaced(name: string): boolean {
+  return parseDocName(name) !== null;
+}
+
+// ---------------------------------------------------------------------------
+// Resolution — where the workspace id and the branch actually come from
+// ---------------------------------------------------------------------------
+
+/**
+ * Current branch, read straight from `.git/HEAD` (no subprocess — the same
+ * source `collab/git-lifecycle.ts` watches).
+ *
+ * A detached HEAD yields `detached-<sha7>`, which is a *stable* name for that
+ * commit: two peers detached at the same commit meet, and a peer on a branch
+ * never accidentally shares a doc with a detached checkout.
+ *
+ * Returns null when there is no git repo at all.
+ */
+export function readBranch(repoRoot: string): string | null {
+  const headPath = path.join(repoRoot, '.git', 'HEAD');
+  if (!existsSync(headPath)) return null;
+  let head: string;
+  try {
+    head = readFileSync(headPath, 'utf8').trim();
+  } catch {
+    return null;
+  }
+  const ref = head.match(/^ref:\s*refs\/heads\/(.+)$/);
+  if (ref?.[1]) return ref[1];
+  if (/^[0-9a-f]{7,40}$/i.test(head)) return `detached-${head.slice(0, 7)}`;
+  return null;
+}
+
+/**
+ * Read the `origin` remote URL from `.git/config` without shelling out.
+ * Returns null when there is no origin (a purely local repo).
+ */
+export function readOriginUrl(repoRoot: string): string | null {
+  const cfgPath = path.join(repoRoot, '.git', 'config');
+  if (!existsSync(cfgPath)) return null;
+  let raw: string;
+  try {
+    raw = readFileSync(cfgPath, 'utf8');
+  } catch {
+    return null;
+  }
+  const section = raw.match(/\[remote "origin"\]([\s\S]*?)(?=\n\[|$)/);
+  const url = section?.[1]?.match(/^\s*url\s*=\s*(.+)$/m)?.[1]?.trim();
+  return url && url.length > 0 ? url : null;
+}
+
+/**
+ * Reduce a git remote URL to a stable `<owner>-<repo>` identity, so
+ * `git@github.com:1aGh/maude.git` and `https://github.com/1aGh/maude` — the
+ * same project cloned two different ways — produce the SAME workspace id.
+ *
+ * Getting this wrong is not a cosmetic bug: two peers of one project that
+ * derive different ids would stop meeting, and each would see the other's docs
+ * as absent.
+ */
+export function workspaceIdFromRemote(url: string): string {
+  let s = url.trim().replace(/\.git$/i, '');
+  s = s.replace(/^[a-z0-9+.-]+:\/\//i, ''); // scheme
+  s = s.replace(/^[^@/]+@/, ''); // user@
+  s = s.replace(/^([^/:]+):/, '$1/'); // scp-style host:path → host/path
+  const segments = s.split('/').filter(Boolean);
+  const tail = segments.slice(-2); // <owner>/<repo>
+  return sanitizeComponent(tail.join('-'));
+}
+
+export interface ResolveWorkspaceOpts {
+  /** Explicit id from config — authoritative when present (the cloud sets it). */
+  explicit?: string | undefined;
+  repoRoot: string;
+}
+
+/**
+ * Resolve the workspace id, or null when it cannot be derived in a way that is
+ * STABLE ACROSS MACHINES.
+ *
+ * Order: explicit config → git origin remote. There is deliberately no
+ * directory-name fallback: a local path is not the same on two machines, so
+ * deriving from it would split peers of the same project into separate
+ * documents — the exact failure the namespace exists to prevent, arrived at
+ * from the other direction. No stable id ⇒ stay flat (see `createDocNameResolver`).
+ */
+export function resolveWorkspaceId({ explicit, repoRoot }: ResolveWorkspaceOpts): string | null {
+  const fromConfig = sanitizeComponent(explicit ?? '');
+  if (fromConfig) return fromConfig;
+  const origin = readOriginUrl(repoRoot);
+  if (!origin) return null;
+  const derived = workspaceIdFromRemote(origin);
+  return derived || null;
+}
+
+export interface DocNameResolver {
+  /** Map a local canvas slug to the name used on the wire. */
+  (slug: string): string;
+}
+
+export interface DocNameResolverOpts {
+  repoRoot: string;
+  /** `linkedHub.workspaceId` when the config carries one. */
+  explicitWorkspaceId?: string | undefined;
+  /** `MAUDE_HUB_NAMESPACED` — '1' forces on, '0' forces off, absent = auto. */
+  flag?: string | undefined;
+  /** Test seam: override branch detection. */
+  branch?: string | undefined;
+}
+
+/**
+ * Build the slug → documentName mapping for this process.
+ *
+ * Rollout rule (DDR-192 §5): namespacing CHANGES DOC IDENTITY, so it is opt-in
+ * for now and becomes default-on in workspace mode (Phase 3).
+ *
+ *   MAUDE_HUB_NAMESPACED=0  → always flat, even with an explicit workspace id
+ *   MAUDE_HUB_NAMESPACED=1  → namespaced, and it is an ERROR to be unable to
+ *                             (an operator who asked for isolation gets a loud
+ *                             failure, never a silent fallback into a shared doc)
+ *   unset                   → namespaced only when config declares a workspace
+ *                             id explicitly; otherwise flat
+ *
+ * The auto case is deliberately NOT "namespace whenever a git origin exists":
+ * flipping identity under an existing linked hub would make every doc look
+ * freshly empty. DDR-076 keeps that from eating local files, but the hub-side
+ * history would be orphaned, and nobody asked for that on upgrade.
+ */
+export function createDocNameResolver(opts: DocNameResolverOpts): DocNameResolver {
+  const flag = opts.flag;
+  if (flag === '0') return (slug) => slug;
+
+  const workspaceId = resolveWorkspaceId({
+    explicit: opts.explicitWorkspaceId,
+    repoRoot: opts.repoRoot,
+  });
+  const branch = sanitizeComponent(opts.branch ?? readBranch(opts.repoRoot) ?? '');
+
+  if (flag === '1') {
+    if (!workspaceId) {
+      throw new Error(
+        'MAUDE_HUB_NAMESPACED=1 but no workspace id could be resolved. Set ' +
+          '`linkedHub.workspaceId` in .design/config.json, or give the repo an ' +
+          '`origin` remote. Refusing to fall back to flat slugs — that would put ' +
+          'this project in a shared document namespace (DDR-192 §5).'
+      );
+    }
+    if (!branch) {
+      throw new Error(
+        'MAUDE_HUB_NAMESPACED=1 but the current branch could not be read from ' +
+          '.git/HEAD. Refusing to fall back to flat slugs (DDR-192 §5).'
+      );
+    }
+  }
+
+  const explicitlyDeclared = sanitizeComponent(opts.explicitWorkspaceId ?? '') !== '';
+  const on = flag === '1' || (explicitlyDeclared && !!workspaceId && !!branch);
+  if (!on || !workspaceId || !branch) return (slug) => slug;
+
+  return (slug) => buildDocName({ workspaceId, branch, slug });
+}

package/apps/studio/sync/index.ts

@@ -28,11 +28,14 @@ import { Y_TYPES } from '../collab/persistence.ts';
 import type { Context } from '../context.ts';
 import { createHistory } from '../history.ts';
 import { type CanvasSyncAgent, createCanvasSyncAgent } from './agent.ts';
+import { atomicWrite } from './atomic-write.ts';
+import { createAutoCommit } from './autocommit.ts';
 import {
   type ConnectionMonitor,
   createConnectionMonitor,
   type ProviderStatus,
 } from './connection-state.ts';
+import { createDocNameResolver } from './doc-name.ts';
 import { createEchoGuard } from './echo-guard.ts';
 import { createFsReader, type FsReader } from './fs-mirror.ts';
 import { getHubToken } from './hubs-config.ts';
@@ -241,6 +244,42 @@ export function createSyncRuntime(
     return null;
   }
 
+  // DDR-192 §5 — slug → wire documentName. Only the WIRE name is namespaced;
+  // every local map (providers, agents, projections, _history/) stays keyed by
+  // the flat slug. Opt-in for now (see createDocNameResolver's rollout rule);
+  // a bad MAUDE_HUB_NAMESPACED=1 with no resolvable workspace id throws here
+  // rather than silently falling back into a shared namespace.
+  let docNameFor: (slug: string) => string;
+  try {
+    docNameFor = createDocNameResolver({
+      repoRoot: ctx.paths.repoRoot,
+      explicitWorkspaceId: linkedHub.workspaceId,
+      flag: process.env.MAUDE_HUB_NAMESPACED,
+    });
+  } catch (err) {
+    console.error(`[sync] refusing to start: ${(err as Error).message}`);
+    return null;
+  }
+
+  // Cloud Phase 3 Task 1 — in a workspace cell, a disk write is only half the
+  // save: nobody is at a keyboard to commit, so the cell does it. Off entirely
+  // outside workspace mode, where the developer's own git IS the history and
+  // committing under them would be an intrusion (DDR-119).
+  const autoCommit =
+    process.env.MAUDE_WORKSPACE_MODE === '1'
+      ? createAutoCommit({
+          repoRoot: ctx.paths.repoRoot,
+          run: async (args, { cwd }) => {
+            const proc = Bun.spawn(['git', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' });
+            const [stdout, stderr] = await Promise.all([
+              new Response(proc.stdout).text(),
+              new Response(proc.stderr).text(),
+            ]);
+            return { code: await proc.exited, stdout, stderr };
+          },
+        })
+      : null;
+
   const resolvedToken = getHubToken(linkedHub.url);
   if (!resolvedToken) {
     console.warn(
@@ -556,6 +595,35 @@ export function createSyncRuntime(
      * permanent-rejection re-probe (which passes the EXISTING doc so the
      * agent/projection wiring — doc-scoped — survives the provider swap).
      */
+    /**
+     * Who is editing this canvas right now, from hub awareness.
+     *
+     * Presence carries a display name and no address, so the address is
+     * synthesized and clearly marked as derived — inventing a plausible-looking
+     * real address would put an unverified identity into permanent git history.
+     * Absent a remote peer the answer is null, which `autocommit` turns into
+     * "Unknown editor" rather than attributing the work to the server.
+     */
+    const editorOf = (slug: string): { name: string; email: string } | null => {
+      const awareness = providers.get(slug)?.awareness;
+      if (!awareness) return null;
+      for (const [clientId, state] of awareness.getStates() as Map<
+        number,
+        { name?: string } | undefined
+      >) {
+        if (clientId === awareness.clientID) continue; // that's us, the cell
+        const name = state?.name?.trim();
+        if (name) {
+          const slugified = name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '-')
+            .replace(/^-|-$/g, '');
+          return { name, email: `${slugified || 'peer'}@peers.maude.local` };
+        }
+      }
+      return null;
+    };
+
     const connectCanvas = async (
       canvas: CanvasDescriptor,
       canvasPaths: import('./agent.ts').CanvasSyncPaths,
@@ -565,7 +633,7 @@ export function createSyncRuntime(
       const provider = await providerFactory({
         url: linkedHub.url,
         token,
-        documentName: canvas.slug,
+        documentName: docNameFor(canvas.slug),
         document,
       });
       providers.set(canvas.slug, provider);
@@ -653,6 +721,20 @@ export function createSyncRuntime(
               echoGuard,
               adopt: adoptOnce,
               journal: journal ?? undefined,
+              // Wrap the writer rather than adding a new hook: every path the
+              // agent materializes to disk goes through it, so a future write
+              // surface is committed automatically instead of being forgotten.
+              ...(autoCommit
+                ? {
+                    writer: (file: string, bytes: string | Uint8Array) => {
+                      atomicWrite(file, bytes);
+                      autoCommit.note(
+                        path.relative(ctx.paths.repoRoot, file),
+                        editorOf(canvas.slug)
+                      );
+                    },
+                  }
+                : {}),
               snapshot: async (content, reason) => {
                 try {
                   const snap = await history.writeSnapshot(relBody, content, reason);
@@ -770,6 +852,18 @@ export function createSyncRuntime(
   async function stop(): Promise<void> {
     if (stopped) return;
     stopped = true;
+    // Commit whatever is still inside the quiescence window BEFORE tearing
+    // anything down. Shutting down mid-window would leave the last edits on
+    // disk but out of history — the one state this whole mechanism exists to
+    // make impossible.
+    if (autoCommit) {
+      try {
+        await autoCommit.flush();
+      } catch (err) {
+        console.error('[sync] final autocommit failed:', err);
+      }
+      autoCommit.stop();
+    }
     for (const detach of awarenessDetaches) {
       try {
         detach();