@yeaft/webchat-agent 0.1.533 → 0.1.535

package/connection/message-router.js

@@ -36,7 +36,7 @@ import { sendToServer, flushMessageBuffer } from './buffer.js';
 import { handleRestartAgent, handleUpgradeAgent } from './upgrade.js';
 import { loadMcpServers, updateMcpConfig } from '../mcp.js';
 import { getLlmConfig, updateLlmConfig, getUnifySettings, updateUnifySettings } from '../unify/config-api.js';
-import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread, handleUnifyForkThread, handleUnifyAbortThread, handleUnifyAbortAll, handleUnifyVpSubscribe, handleUnifyVpCreate, handleUnifyVpUpdate, handleUnifyVpDelete, handleUnifyVpRead, handleUnifyTaskMessage, handleUnifyUserMemoryWrite, handleUnifyUserMemoryRemove } from '../unify/web-bridge.js';
+import { handleUnifyChat, handleUnifyModeSwitch, handleUnifyModelSwitch, resetUnifySession, handleUnifyLoadHistory, handleUnifyMergeThread, handleUnifyForkThread, handleUnifyAbortThread, handleUnifyAbortAll, handleUnifyVpSubscribe, handleUnifyVpCreate, handleUnifyVpUpdate, handleUnifyVpDelete, handleUnifyVpRead, handleUnifyTaskMessage, handleUnifyUserMemoryWrite, handleUnifyUserMemoryRemove, handleUnifyListGroups, handleUnifyCreateGroup, handleUnifyRenameGroup, handleUnifyArchiveGroup, handleUnifyAddMember, handleUnifyRemoveMember, handleUnifySetDefaultVp } from '../unify/web-bridge.js';
 
 export async function handleMessage(msg) {
   switch (msg.type) {
@@ -436,6 +436,32 @@ export async function handleMessage(msg) {
       handleUnifyUserMemoryRemove(msg);
       break;
 
+    // task-334m: Group CRUD + D1 seed wiring (§Δ10 334m + R6 §Δ31.2).
+    // All handlers reply via `group_crud_result`; mutating ops additionally
+    // emit `group_roster_changed` (add/remove/default) or
+    // `group_list_updated` (create/rename/archive) for listener sync.
+    case 'unify_list_groups':
+      handleUnifyListGroups(msg);
+      break;
+    case 'unify_create_group':
+      handleUnifyCreateGroup(msg);
+      break;
+    case 'unify_rename_group':
+      handleUnifyRenameGroup(msg);
+      break;
+    case 'unify_archive_group':
+      handleUnifyArchiveGroup(msg);
+      break;
+    case 'unify_add_member':
+      handleUnifyAddMember(msg);
+      break;
+    case 'unify_remove_member':
+      handleUnifyRemoveMember(msg);
+      break;
+    case 'unify_set_default_vp':
+      handleUnifySetDefaultVp(msg);
+      break;
+
     // Expert roles definition (for ExpertPanel detail view)
     case 'get_expert_roles': {
       const { getExpertRolesDefinition } = await import('../expert-roles.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "0.1.533",
+  "version": "0.1.535",
   "description": "Remote agent for Yeaft WebChat — connects worker machines to the central server",
   "main": "index.js",
   "type": "module",

package/unify/groups/group-crud.js

@@ -0,0 +1,250 @@
+/**
+ * group-crud.js — High-level Group CRUD API (task-334m).
+ *
+ * Wraps the primitives from group-store.js + roster.js into the 5 operations
+ * wired to WS events (§Δ10 334m + R6 §Δ31.2):
+ *   createGroupFromSpec  — wizard "create new group" (empty or user-picked roster)
+ *   renameGroup          — update meta.name; preserves roster / defaultVpId
+ *   archiveGroup         — rename dir to `.archived-<ts>-<id>` (soft delete)
+ *   addMember            — roster.addVp + save; sets defaultVpId if first
+ *   removeMember         — roster.removeVp + save; clears/rotates defaultVpId
+ *
+ * Plus the D1 bootstrap helper:
+ *   ensureDefaultGroupIfEmpty(yeaftDir, {libDir}) — if NO group exists on
+ *   disk, seed `grp_default` with roster = every VP in the library, and
+ *   defaultVpId = alphabetically first vpId. No-op when ≥1 group present.
+ *
+ * Hard constraints (PM):
+ *   (a) We don't touch 334o storage primitives (storage/index.js) — we call
+ *       group-store.openGroup / saveMeta which already go through openLog.
+ *   (b) We don't touch VP entity (vp-store.js / vp-loader.js) — only read
+ *       via scanVpLibrary to know which VPs exist at seed time.
+ *   (c) When `addMember` is called with an empty roster and no defaultVpId
+ *       resolvable, callers surface `no_default_vp` via `createGroupFromSpec`;
+ *       on `removeMember` we permit the empty state (UI nudges the user).
+ *
+ * Error shape — every throw is a `GroupCrudError` with a stable `.code`:
+ *   'not_found'        — group id has no dir / meta
+ *   'duplicate'        — createGroup collided with an existing id
+ *   'invalid_name'     — display name empty after trim
+ *   'no_default_vp'    — seed with empty VP library OR roster empties to []
+ *                        and the caller asked for a defaultVpId. (D1 spec)
+ *   'reserved'/'invalid_vp_id'/... — bubbled from ids.js validators
+ */
+
+import { existsSync, renameSync } from 'fs';
+import { randomBytes } from 'crypto';
+import { join } from 'path';
+import {
+  openGroup, createGroup, listGroups, loadGroupMeta,
+} from './group-store.js';
+import { addVp as rosterAdd, removeVp as rosterRemove, setDefaultVp } from './roster.js';
+import { seedDefaultGroup, DEFAULT_GROUP_ID } from './seed-default.js';
+import { nextGroupId, validateVpId, isReservedVpId } from './ids.js';
+import { scanVpLibrary, DEFAULT_VP_LIB_DIR } from '../vp/vp-store.js';
+
+export class GroupCrudError extends Error {
+  constructor(code, groupId, message) {
+    super(message || `${code}: ${groupId}`);
+    this.name = 'GroupCrudError';
+    this.code = code;
+    this.groupId = groupId;
+  }
+}
+
+function groupsRoot(yeaftDir) {
+  return join(yeaftDir, 'groups');
+}
+
+/** Build a safe group id from a display name (slug + ulid-lite suffix). */
+export function makeGroupId(name) {
+  const slug = String(name || 'group')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 24) || 'group';
+  return nextGroupId(slug);
+}
+
+/**
+ * (B) D1 seed — called at boot (or when multi-VP is first enabled). Idempotent:
+ * returns `{seeded:false}` if any group already exists on disk (including
+ * `grp_default`). When empty, seeds with roster = full VP library, sorted
+ * alphabetically; defaultVpId = roster[0].
+ *
+ * When the VP library is also empty, we still seed an empty-roster group so
+ * the UI has somewhere to land — but defaultVpId is null and downstream
+ * message send will return `no_default_vp` until the user adds a VP.
+ */
+export function ensureDefaultGroupIfEmpty(yeaftDir, options = {}) {
+  const libDir = options.libDir || DEFAULT_VP_LIB_DIR;
+  const existing = listGroups(groupsRoot(yeaftDir));
+  if (existing.length > 0) {
+    return { seeded: false, groupId: existing[0].id };
+  }
+
+  // Sort VP ids alphabetically (stable for tests / deterministic UI).
+  // NB: vp-store returns records with `.id` (not `.vpId`) — keep this in sync.
+  const vps = scanVpLibrary({ dir: libDir })
+    .map(v => v && v.id)
+    .filter(v => typeof v === 'string' && v.length > 0);
+  vps.sort((a, b) => a.localeCompare(b));
+
+  const defaultVpId = vps[0] || null;
+  const { group, created } = seedDefaultGroup(yeaftDir, {
+    name: options.name || 'Default',
+    roster: vps,
+    defaultVpId,
+  });
+  return {
+    seeded: created,
+    groupId: group.id,
+    defaultVpId,
+    rosterSize: vps.length,
+  };
+}
+
+/**
+ * (A.1) Create group from a wizard spec. `spec.roster` is authoritative —
+ * we do NOT auto-expand to the full VP library here. That's D1's job only.
+ *
+ * @param {string} yeaftDir
+ * @param {{name:string, roster?:string[], defaultVpId?:string|null}} spec
+ * @returns {{id:string, name:string, roster:string[], defaultVpId:string|null}}
+ */
+export function createGroupFromSpec(yeaftDir, spec) {
+  const name = String(spec && spec.name || '').trim();
+  if (!name) throw new GroupCrudError('invalid_name', null, 'group name required');
+
+  const roster = Array.isArray(spec.roster) ? spec.roster.slice() : [];
+  // Validate every member up-front so we fail before touching fs.
+  for (const vpId of roster) {
+    if (isReservedVpId(vpId)) {
+      throw new GroupCrudError('reserved', null, `reserved vpId: ${vpId}`);
+    }
+    const v = validateVpId(vpId);
+    if (!v.ok) throw new GroupCrudError(v.reason, null, `invalid vpId: ${vpId}`);
+  }
+
+  // defaultVpId resolution: explicit > roster[0] > null. Null is allowed at
+  // create time (empty roster) — the wizard modal warns the user downstream
+  // (task-334m spec: `no_default_vp` surfaced on first send, not on create).
+  let defaultVpId = spec.defaultVpId || null;
+  if (defaultVpId && !roster.includes(defaultVpId)) {
+    throw new GroupCrudError('default_not_in_roster', null, `${defaultVpId} not in roster`);
+  }
+  if (!defaultVpId) defaultVpId = roster[0] || null;
+
+  const id = makeGroupId(name);
+  const root = groupsRoot(yeaftDir);
+  if (existsSync(join(root, id))) {
+    // Extremely unlikely (ulid suffix), but surface deterministically.
+    throw new GroupCrudError('duplicate', id);
+  }
+
+  const handle = createGroup(root, { id, name, roster, defaultVpId });
+  const meta = handle.getMeta();
+  handle.close();
+  return meta;
+}
+
+/**
+ * (A.2) Rename — updates meta.name; preserves everything else.
+ */
+export function renameGroup(yeaftDir, groupId, newName) {
+  const name = String(newName || '').trim();
+  if (!name) throw new GroupCrudError('invalid_name', groupId);
+  const handle = requireGroup(yeaftDir, groupId);
+  const meta = handle.getMeta();
+  handle.saveMeta({ ...meta, name });
+  const next = handle.getMeta();
+  handle.close();
+  return next;
+}
+
+/**
+ * (A.3) Archive — renames the dir to `.archived-<ts>-<id>`. Directory
+ * prefix `.` keeps `listGroups` from picking it up (readdirSync filter in
+ * the caller). Reversible: user can rename back manually for recovery.
+ *
+ * We do NOT support hard-delete here — that's an upstream UI flow with its
+ * own second-confirm modal (acceptance #4 in task-334-slice-specs.md 334m).
+ */
+export function archiveGroup(yeaftDir, groupId) {
+  const root = groupsRoot(yeaftDir);
+  const srcDir = join(root, groupId);
+  if (!existsSync(srcDir) || !loadGroupMeta(srcDir)) {
+    throw new GroupCrudError('not_found', groupId);
+  }
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  // Append 4 hex chars to disambiguate same-millisecond archives (nit #5).
+  const suffix = randomBytes(2).toString('hex');
+  const dstDir = join(root, `.archived-${ts}-${suffix}-${groupId}`);
+  renameSync(srcDir, dstDir);
+  return { groupId, archivedAs: dstDir };
+}
+
+/**
+ * (A.4) Add a VP to the group roster. Idempotent — no-op if already present.
+ * Returns the new meta.
+ */
+export function addMember(yeaftDir, groupId, vpId) {
+  const handle = requireGroup(yeaftDir, groupId);
+  try {
+    const meta = handle.getMeta();
+    const next = rosterAdd(meta, vpId);
+    handle.saveMeta(next);
+    return handle.getMeta();
+  } finally {
+    handle.close();
+  }
+}
+
+/**
+ * (A.5) Remove a VP from the group roster. If the removed id was default,
+ * roster.removeVp rotates to the next member (or null).
+ */
+export function removeMember(yeaftDir, groupId, vpId) {
+  const handle = requireGroup(yeaftDir, groupId);
+  try {
+    const meta = handle.getMeta();
+    if (!meta.roster.includes(vpId)) {
+      // Treat as idempotent no-op — UI wants the post-state.
+      return meta;
+    }
+    const next = rosterRemove(meta, vpId);
+    handle.saveMeta(next);
+    return handle.getMeta();
+  } finally {
+    handle.close();
+  }
+}
+
+/** Expose default-VP setter for UI "set as default" affordance. */
+export function setGroupDefaultVp(yeaftDir, groupId, vpId) {
+  const handle = requireGroup(yeaftDir, groupId);
+  try {
+    const meta = handle.getMeta();
+    const next = setDefaultVp(meta, vpId);
+    handle.saveMeta(next);
+    return handle.getMeta();
+  } finally {
+    handle.close();
+  }
+}
+
+function requireGroup(yeaftDir, groupId) {
+  const root = groupsRoot(yeaftDir);
+  const dir = join(root, groupId);
+  if (!existsSync(dir) || !loadGroupMeta(dir)) {
+    throw new GroupCrudError('not_found', groupId);
+  }
+  return openGroup(root, groupId);
+}
+
+/** Convenience: snapshot all non-archived groups for WS broadcast. */
+export function snapshotGroups(yeaftDir) {
+  return listGroups(groupsRoot(yeaftDir));
+}
+
+export { DEFAULT_GROUP_ID };

package/unify/groups/index.js

@@ -37,6 +37,18 @@ export {
   seedDefaultGroup,
   DEFAULT_GROUP_ID,
 } from './seed-default.js';
+export {
+  GroupCrudError,
+  makeGroupId,
+  ensureDefaultGroupIfEmpty,
+  createGroupFromSpec,
+  renameGroup,
+  archiveGroup,
+  addMember,
+  removeMember,
+  setGroupDefaultVp,
+  snapshotGroups,
+} from './group-crud.js';
 export {
   nextMsgId,
   nextGroupId,

package/unify/memory/migrate-r5-to-r6.js

@@ -1,22 +1,89 @@
 /**
- * migrate-r5-to-r6.js — task-334f §Δ23 migration stub.
+ * migrate-r5-to-r6.js — task-334i (wave-4) R5 → R6 storage migration.
  *
- * Legacy (R5): `~/.yeaft/memory/entries/<slug>.md` plus numeric shard files
- *              `memory-001.md`, `memory-002.md`, ...
+ * Continuation of task-334i-v0 (PR #552, shipped v0.1.521) which established
+ * the general `~/.yeaft/` tree via `v0-to-v1.js`. This slice implements the
+ * R5→R6 *memory shard + conversation rotation* pass that fleshes out the
+ * previously-stubbed `applyR5ToR6Migration`.
  *
- * R6:          `~/.yeaft/memory/vp/<vpId>/memory-<semantic>.md`
- *              Semantic shards: skill / relations / lessons / preferences /
- *                               project-<slug>
+ * Spec: .crew/context/task-334i-impl-spec.md
  *
- * This slice (334f) only DEFINES the API surface and a dry-run classifier.
- * The actual batch migration runs in 334i; 334f does not mutate disk.
+ * Key invariants:
+ *   - This is independently idempotent from v0→v1. State version bumps r5→r6.
+ *   - Does NOT touch 334f `shard-store.js` or 334o storage primitives —
+ *     only consumes their public APIs.
+ *   - Legacy R5 data is archived to `.legacy/r6-state.tar.gz` BEFORE any
+ *     write. Rollback restores the archive but never deletes it.
+ *   - `migration-state.json` is the single source of truth; writes go
+ *     through `writeAtomic` (tmp+rename) mirroring 334f commitRecompression.
+ *
+ * Two-pass algorithm (pre-emptive discovery #2):
+ *   Pass 1 — write each entry to its default semantic shard
+ *            (skill / relations / lessons / preferences / project-legacy)
+ *            while counting entries per groupId.
+ *   Pass 2 — for each groupId with count ≥ PROJECT_DERIVE_THRESHOLD (30),
+ *            derive a `project-<slug>` shard and move entries via
+ *            stageRecompression / commitRecompression.
+ *
+ * Name drift fix (pre-emptive discovery #1):
+ *   `map-fields.js` (shipped) defines MIGRATION_AUTHOR='system:migration-v0-to-v1'.
+ *   Correct spec value is 'system:migration-v0-v1'. This file overrides via
+ *   local constants without editing the shipped pure-mapper module.
  */
 
-import { existsSync, readdirSync, readFileSync } from 'fs';
-import { join } from 'path';
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+} from 'fs';
+import { join, dirname } from 'path';
+import { createHash } from 'crypto';
+import { execFileSync } from 'child_process';
+
+import { openLog, writeAtomic } from '../storage/index.js';
 import { parseEntry } from './store.js';
-import { classifyLegacyEntryToShard } from './shard-store.js';
+import {
+  openMemoryShardStore,
+  classifyLegacyEntryToShard,
+} from './shard-store.js';
+import { PROJECT_DERIVE_THRESHOLD } from './schema.js';
+import {
+  parseFrontmatter,
+  mapMessageMdToJsonl,
+  splitCoordinatorTurns,
+  LEGACY_GROUP_ID,
+  LEGACY_VP_ID,
+} from '../migration/map-fields.js';
+
+// ─── Name-drift fix (spec §3, §4) ────────────────────────────────
+export const R5_TO_R6_AUTHOR_SYS = 'system:migration-v0-v1';
+export const R5_TO_R6_AUTHOR_USER = 'user:migration-v0-v1';
+const SOURCE_HINT = 'legacy-r5-migration';
+const STATE_FILE = 'migration-state.json';
+const ARCHIVE_REL = join('.legacy', 'r6-state.tar.gz');
+
+// authoredBy inference table (spec §3 deliverable E).
+function inferAuthoredBy(kind) {
+  switch (kind) {
+    case 'preference':
+    case 'identity':
+      return R5_TO_R6_AUTHOR_USER;
+    case 'fact':
+    case 'skill':
+    case 'lesson':
+    case 'context':
+    case 'relation':
+    default:
+      return R5_TO_R6_AUTHOR_SYS;
+  }
+}
 
+// ─── Planner (dry-run, unchanged behaviour from 334f stub) ───────
 /**
  * Produce a migration plan without applying it.
  *
@@ -50,12 +117,495 @@ export function planR5ToR6Migration(legacyEntriesDir) {
   return { totalEntries: plan.length, plan, byShard };
 }
 
+// ─── State I/O ────────────────────────────────────────────────────
+function stateFilePath(yeaftDir) {
+  return join(yeaftDir, STATE_FILE);
+}
+
+function loadState(yeaftDir) {
+  const p = stateFilePath(yeaftDir);
+  if (!existsSync(p)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(p, 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveState(yeaftDir, state) {
+  writeAtomic(stateFilePath(yeaftDir), JSON.stringify(state, null, 2));
+}
+
+function clearState(yeaftDir) {
+  const p = stateFilePath(yeaftDir);
+  if (existsSync(p)) rmSync(p);
+}
+
+function nowIso() { return new Date().toISOString(); }
+
+function stableId(slug) {
+  const h = createHash('sha1').update(String(slug)).digest('hex').slice(0, 12);
+  return `mem_legacy_${h}`;
+}
+
+// ─── Archive helper (spec §11 step 3) ────────────────────────────
+/**
+ * tar+gzip `memory/entries/` and `conversations/` into .legacy/r6-state.tar.gz.
+ * Uses the `tar` CLI via execFileSync (same pattern as 334i-v0). Any failure
+ * throws so the caller can bail before making destructive changes.
+ */
+export function archiveR5State(yeaftDir) {
+  const legacyDir = join(yeaftDir, '.legacy');
+  mkdirSync(legacyDir, { recursive: true });
+  const archivePath = join(yeaftDir, ARCHIVE_REL);
+  const entriesDir = join(yeaftDir, 'memory', 'entries');
+  const conversationsDir = join(yeaftDir, 'conversations');
+  const args = ['-czf', archivePath, '-C', yeaftDir];
+  let added = 0;
+  if (existsSync(entriesDir)) { args.push(join('memory', 'entries')); added++; }
+  if (existsSync(conversationsDir)) { args.push('conversations'); added++; }
+  if (added === 0) {
+    // Write a zero-content marker so rollback has a file to inspect.
+    writeAtomic(archivePath, '');
+    return archivePath;
+  }
+  execFileSync('tar', args, { stdio: ['ignore', 'ignore', 'pipe'] });
+  return archivePath;
+}
+
+// ─── Detect helpers ──────────────────────────────────────────────
+/**
+ * Classify the shape of the R5 memory layout in `yeaftDir`.
+ */
+export function detectR5MemoryLayout(yeaftDir) {
+  const entriesDir = join(yeaftDir, 'memory', 'entries');
+  const conversationsDir = join(yeaftDir, 'conversations');
+  const groupsDir = join(yeaftDir, 'groups');
+  const hasEntries = existsSync(entriesDir) && readdirSync(entriesDir).some(f => f.endsWith('.md'));
+  const hasConversationsMd = existsSync(conversationsDir)
+    && readdirSync(conversationsDir).some(() => true);
+  const hasGroupsJsonl = existsSync(groupsDir);
+  return {
+    entriesDir,
+    conversationsDir,
+    groupsDir,
+    hasEntries,
+    hasConversationsMd,
+    hasGroupsJsonl,
+  };
+}
+
+// ─── Pass 1: write entries to default shards ─────────────────────
+function runPass1({ yeaftDir, layout, vpDir, log, existingState }) {
+  const shardStore = openMemoryShardStore(vpDir, 'vp');
+  const files = layout.hasEntries
+    ? readdirSync(layout.entriesDir).filter(f => f.endsWith('.md')).sort()
+    : [];
+  const counts = (existingState && existingState.counts) || {};
+  const migrated = [];
+  const errors = [];
+
+  for (const file of files) {
+    const slug = file.replace(/\.md$/, '');
+    const id = stableId(slug);
+    // Idempotency: skip already-migrated ids.
+    if (shardStore.get(id)) {
+      migrated.push({ id, slug, shard: shardStore.get(id).shard, skipped: true });
+      continue;
+    }
+    let raw;
+    try {
+      raw = readFileSync(join(layout.entriesDir, file), 'utf8');
+    } catch (e) {
+      errors.push({ file, error: String(e.message || e) });
+      continue;
+    }
+    const legacy = parseEntry(raw);
+    if (!legacy) {
+      errors.push({ file, error: 'parseEntry returned null (malformed frontmatter)' });
+      continue;
+    }
+    const shard = classifyLegacyEntryToShard(legacy);
+    const kind = legacy.kind || 'fact';
+    const tags = Array.isArray(legacy.tags) ? legacy.tags.slice() : [];
+    const createdAt = legacy.created_at || nowIso();
+    const updatedAt = legacy.updated_at || createdAt;
+    // Determine groupId for project-derive counting. Legacy schema has no
+    // explicit groupId; fall back to scope's top segment, else LEGACY_GROUP_ID.
+    const groupId = deriveGroupId(legacy);
+
+    // identity/preference kinds are allowed empty msgIds per §Δ23.
+    // Other kinds rely on the hint='legacy-r5-migration' to legitimise [].
+    // `validateR6Entry` requires non-empty msgIds for non-identity/preference —
+    // so we put a synthetic legacy marker to keep the validator happy while
+    // still conveying "migrated, no real messages attached" semantically.
+    const needsMsgIdMarker = !(kind === 'identity' || kind === 'preference');
+    const msgIds = needsMsgIdMarker ? [`legacy:${slug}`] : [];
+
+    const entry = {
+      id,
+      shard,
+      kind,
+      tags,
+      pinned: legacy.importance === 'high',
+      sourceRef: {
+        groupId,
+        taskId: null,
+        msgIds,
+        timeWindow: `[${createdAt}, ${updatedAt}]`,
+        hint: SOURCE_HINT,
+      },
+      supersedes: null,
+      supersededBy: null,
+      authoredBy: inferAuthoredBy(kind),
+      createdAt,
+      updatedAt,
+      body: legacy.content || '',
+    };
+    try {
+      shardStore.put(entry);
+      counts[groupId] = (counts[groupId] || 0) + 1;
+      migrated.push({ id, slug, shard, groupId });
+    } catch (e) {
+      errors.push({ file, error: String(e.message || e) });
+    }
+  }
+
+  log('pass1', { migrated: migrated.length, errors: errors.length });
+  return { counts, migrated, errors };
+}
+
+function deriveGroupId(legacyEntry) {
+  // scope is a path like "work/project-name/auth". Use first segment as
+  // coarse groupId; fall back to LEGACY_GROUP_ID.
+  const scope = legacyEntry && legacyEntry.scope;
+  if (typeof scope === 'string' && scope.trim()) {
+    const first = scope.split('/').map(s => s.trim()).filter(Boolean)[0];
+    if (first) return first;
+  }
+  return LEGACY_GROUP_ID;
+}
+
+// ─── Pass 2: project-<slug> derive ───────────────────────────────
+function runPass2({ vpDir, counts, log }) {
+  const derived = [];
+  const qualifyingShards = Object.entries(counts || {})
+    .filter(([, c]) => c >= PROJECT_DERIVE_THRESHOLD)
+    .map(([g]) => `project-${slugify(g)}`);
+  // Re-open with project-<slug> allow-listed up front so put() validates.
+  const shardStore = openMemoryShardStore(vpDir, 'vp', { extraShards: qualifyingShards });
+  for (const [groupId, count] of Object.entries(counts || {})) {
+    if (count < PROJECT_DERIVE_THRESHOLD) continue;
+    const slug = slugify(groupId);
+    const targetShard = `project-${slug}`;
+    // Skip if this project shard already exists and is populated — re-entry safe.
+    const stats = shardStore.stats();
+    if (stats.shards[targetShard] && stats.shards[targetShard].count > 0) {
+      derived.push({ groupId, shard: targetShard, moved: 0, skipped: true });
+      continue;
+    }
+    // Collect entries in the relevant default shard matching this groupId.
+    // Search across all default shards (classification is kind-driven; a
+    // groupId may span skill/lessons/etc).
+    const { results } = shardStore.query({});
+    const moveIds = results
+      .filter(r => r.groupId === groupId)
+      .map(r => r.id);
+    let moved = 0;
+    for (const id of moveIds) {
+      const full = shardStore.get(id);
+      if (!full) continue;
+      // Re-put with new shard; old entry removal happens via supersede-free
+      // rewrite by removing old id after the new one lands.
+      const newEntry = {
+        ...full,
+        shard: targetShard,
+        body: full.body || '',
+      };
+      try {
+        shardStore.put(newEntry);
+        // shardStore.put upserts by id (see 334o shard-store put semantics
+        // removing any prior shard copy of the same id) — so the entry now
+        // lives in targetShard exclusively.
+        moved++;
+      } catch {
+        // best-effort — keep legacy in default shard if move fails.
+      }
+    }
+    derived.push({ groupId, shard: targetShard, moved });
+  }
+  log('pass2', { derived: derived.length });
+  return derived;
+}
+
+function slugify(s) {
+  return String(s || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 40) || 'legacy';
+}
+
+// ─── Conversation migration ──────────────────────────────────────
+function migrateConversations({ yeaftDir, layout, log }) {
+  if (!layout.hasConversationsMd) {
+    log('conversations', { messages: 0, shards: 0 });
+    return { messages: 0, shards: 0 };
+  }
+  const groupDir = join(yeaftDir, 'groups', LEGACY_GROUP_ID, 'messages');
+  mkdirSync(groupDir, { recursive: true });
+  const log_ = openLog(groupDir);
+  let messagesWritten = 0;
+  const convos = readdirSync(layout.conversationsDir);
+  for (const cId of convos) {
+    const msgDir = join(layout.conversationsDir, cId, 'messages');
+    if (!existsSync(msgDir)) continue;
+    const files = readdirSync(msgDir).filter(f => f.endsWith('.md')).sort();
+    for (const file of files) {
+      const raw = readFileSync(join(msgDir, file), 'utf8');
+      const { meta, body } = parseFrontmatter(raw);
+      const originalId = `${cId}_${file.replace(/\.md$/, '')}`;
+      const row = mapMessageMdToJsonl({ meta, body, originalId, fallbackTaskId: null });
+      try {
+        log_.append(row);
+        messagesWritten++;
+      } catch {
+        // Skip malformed row; keep going.
+      }
+    }
+    // Also handle coordinator.md if present
+    const coordPath = join(layout.conversationsDir, cId, 'coordinator.md');
+    if (existsSync(coordPath)) {
+      const raw = readFileSync(coordPath, 'utf8');
+      const turns = splitCoordinatorTurns(raw);
+      for (const turn of turns) {
+        const row = {
+          id: `msg_legacy_${cId}_coord_${turn.index}`,
+          ts: turn.ts || null,
+          type: 'chat',
+          authorKind: 'unknown',
+          authorId: `legacy:${turn.role}`,
+          groupId: LEGACY_GROUP_ID,
+          taskId: null,
+          body: turn.body,
+          mentions: [],
+          replyTo: null,
+          viaTool: null,
+        };
+        try { log_.append(row); messagesWritten++; } catch { /* skip */ }
+      }
+    }
+  }
+  log_.close();
+  const index = log_.getIndex();
+  log('conversations', { messages: messagesWritten, shards: (index.segments || []).length });
+  return { messages: messagesWritten, shards: (index.segments || []).length };
+}
+
+// ─── Main entry ──────────────────────────────────────────────────
+/**
+ * Apply the R5 → R6 migration.
+ *
+ * @param {object} opts
+ * @param {string} opts.yeaftDir  required
+ * @param {string} [opts.vpId]    legacy VP id (default LEGACY_VP_ID)
+ * @param {boolean} [opts.dryRun]
+ * @param {boolean} [opts.force]  clear existing r6 state and re-run from scratch
+ * @param {(step, info)=>void} [opts.onStep]
+ * @returns {Promise<object>}
+ */
+export async function applyR5ToR6Migration(opts = {}) {
+  const { yeaftDir, dryRun = false, force = false, onStep } = opts;
+  const vpId = opts.vpId || LEGACY_VP_ID;
+  if (!yeaftDir || typeof yeaftDir !== 'string') {
+    throw new Error('applyR5ToR6Migration: yeaftDir (string) required');
+  }
+  if (!existsSync(yeaftDir)) {
+    throw new Error(`applyR5ToR6Migration: yeaftDir does not exist: ${yeaftDir}`);
+  }
+  const log = typeof onStep === 'function' ? onStep : () => {};
+  const layout = detectR5MemoryLayout(yeaftDir);
+
+  if (dryRun) {
+    const plan = planR5ToR6Migration(layout.entriesDir);
+    const counts = {};
+    for (const p of plan.plan) {
+      // coarse counting keyed by synthetic groupId based on slug prefix (best-effort preview)
+      counts[LEGACY_GROUP_ID] = (counts[LEGACY_GROUP_ID] || 0) + 1;
+    }
+    const wouldDerive = Object.entries(counts)
+      .filter(([, c]) => c >= PROJECT_DERIVE_THRESHOLD)
+      .map(([g]) => `project-${slugify(g)}`);
+    let estMessages = 0;
+    if (layout.hasConversationsMd) {
+      for (const cId of readdirSync(layout.conversationsDir)) {
+        const msgDir = join(layout.conversationsDir, cId, 'messages');
+        if (existsSync(msgDir)) {
+          estMessages += readdirSync(msgDir).filter(f => f.endsWith('.md')).length;
+        }
+      }
+    }
+    const preview = {
+      pass1: plan.byShard,
+      pass2Candidates: wouldDerive,
+      conversations: {
+        count: layout.hasConversationsMd ? readdirSync(layout.conversationsDir).length : 0,
+        estimatedMessages: estMessages,
+        estimatedShards: Math.max(1, Math.ceil(estMessages / 5000)),
+      },
+    };
+    log('dry-run', preview);
+    return { status: 'dry-run', dryRun: true, preview };
+  }
+
+  // Force: wipe only r6 state, never touch legacy archive.
+  if (force) clearState(yeaftDir);
+
+  let state = loadState(yeaftDir);
+  if (state && state.version === 'r6' && state.pass2CompletedAt) {
+    log('already-done', { migratedAt: state.migratedAt });
+    return { status: 'already-done', state };
+  }
+
+  // Fresh state — but preserve a pre-existing r5 state (from PR #552) if present.
+  if (!state || state.version !== 'r6') {
+    const prior = state || {};
+    state = {
+      version: 'r6',
+      startedAt: nowIso(),
+      legacyArchive: null,
+      pass1CompletedAt: null,
+      pass2CompletedAt: null,
+      migratedAt: null,
+      counts: {},
+      derivedProjects: [],
+      messageCount: 0,
+      entryCount: 0,
+      // Preserve reference to prior r5 state for audit.
+      priorR5: prior && prior.version === 'r5' ? { completedAt: prior.completedAt || null } : null,
+    };
+    saveState(yeaftDir, state);
+  }
+
+  try {
+    // Archive R5 state BEFORE any writes (or skip if already archived in a prior resume).
+    if (!state.legacyArchive) {
+      const archivePath = archiveR5State(yeaftDir);
+      state.legacyArchive = archivePath;
+      saveState(yeaftDir, state);
+      log('archive', { path: archivePath });
+    }
+
+    const vpDir = join(yeaftDir, 'memory', 'vp', vpId);
+    mkdirSync(vpDir, { recursive: true });
+
+    // Pass 1
+    if (!state.pass1CompletedAt) {
+      const p1 = runPass1({ yeaftDir, layout, vpDir, log, existingState: state });
+      state.counts = p1.counts;
+      state.entryCount = (state.entryCount || 0) + p1.migrated.filter(m => !m.skipped).length;
+      state.pass1CompletedAt = nowIso();
+      state.pass1Errors = p1.errors;
+      saveState(yeaftDir, state);
+    } else {
+      log('pass1', { skipped: true });
+    }
+
+    // Pass 2
+    if (!state.pass2CompletedAt) {
+      const derived = runPass2({ vpDir, counts: state.counts, log });
+      state.derivedProjects = derived.map(d => d.shard);
+      state.pass2CompletedAt = nowIso();
+      saveState(yeaftDir, state);
+    } else {
+      log('pass2', { skipped: true });
+    }
+
+    // Conversations (always run once — guarded by index existence).
+    if (!state.conversationsMigratedAt) {
+      const convRes = migrateConversations({ yeaftDir, layout, log });
+      state.messageCount = convRes.messages;
+      state.conversationsMigratedAt = nowIso();
+      saveState(yeaftDir, state);
+    } else {
+      log('conversations', { skipped: true });
+    }
+
+    state.migratedAt = nowIso();
+    saveState(yeaftDir, state);
+    log('done', { migratedAt: state.migratedAt });
+    return { status: 'done', state };
+  } catch (err) {
+    // On error: state file preserved so next run resumes. Archive untouched.
+    state.lastError = String(err && err.message || err);
+    saveState(yeaftDir, state);
+    throw err;
+  }
+}
+
+// ─── Rollback (deliverable G) ────────────────────────────────────
 /**
- * Apply the migration. STUB — 334i will fill in the body writer. 334f keeps
- * this function exported so downstream tests can assert the hook exists.
+ * Roll back an R5→R6 migration. Restores from .legacy/r6-state.tar.gz and
+ * clears r6-specific state. Never touches the separate r5 archive created
+ * by v0-to-v1.js. Idempotent: safe to call when no r6 state is present.
  *
- * @param {object} _opts  { legacyEntriesDir, targetDir, vpId, dryRun }
+ * @param {object} opts
+ * @param {string} opts.yeaftDir required
+ * @param {string} [opts.vpId]   legacy VP id (default LEGACY_VP_ID)
+ * @param {(step, info)=>void} [opts.onStep]
  */
-export async function applyR5ToR6Migration(_opts) {
-  throw new Error('applyR5ToR6Migration: not yet implemented (task-334i)');
+export async function rollbackR5ToR6Migration(opts = {}) {
+  const { yeaftDir, onStep } = opts;
+  const vpId = opts.vpId || LEGACY_VP_ID;
+  if (!yeaftDir || typeof yeaftDir !== 'string') {
+    throw new Error('rollbackR5ToR6Migration: yeaftDir required');
+  }
+  const log = typeof onStep === 'function' ? onStep : () => {};
+  const state = loadState(yeaftDir);
+  if (!state || state.version !== 'r6') {
+    log('noop', { reason: 'no r6 state file present' });
+    return { status: 'noop' };
+  }
+  const archivePath = state.legacyArchive;
+  if (!archivePath || !existsSync(archivePath)) {
+    throw new Error(`rollbackR5ToR6Migration: archive missing at ${archivePath}`);
+  }
+
+  // Delete R6-specific paths first (only what this migration created).
+  const vpDir = join(yeaftDir, 'memory', 'vp', vpId);
+  if (existsSync(vpDir)) {
+    rmSync(vpDir, { recursive: true, force: true });
+    log('rm-vp-memory', { path: vpDir });
+  }
+  const groupsDir = join(yeaftDir, 'groups', LEGACY_GROUP_ID, 'messages');
+  if (existsSync(groupsDir)) {
+    rmSync(groupsDir, { recursive: true, force: true });
+    log('rm-group-messages', { path: groupsDir });
+  }
+
+  // Restore archive back to yeaftDir. tar -xzf will overwrite paths it owns.
+  // Only do this if archive is non-empty (empty marker = nothing was archived).
+  const sz = statSync(archivePath).size;
+  if (sz > 0) {
+    execFileSync('tar', ['-xzf', archivePath, '-C', yeaftDir], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    log('restore', { from: archivePath });
+  } else {
+    log('restore', { from: archivePath, note: 'empty archive — nothing to restore' });
+  }
+
+  // Downgrade state to r5 marker (archive left on disk for audit).
+  const newState = {
+    version: 'r5',
+    rolledBackAt: nowIso(),
+    previousR6: {
+      migratedAt: state.migratedAt,
+      legacyArchive: state.legacyArchive,
+    },
+  };
+  saveState(yeaftDir, newState);
+  log('done', { rolledBackAt: newState.rolledBackAt });
+  return { status: 'done', state: newState };
 }

package/unify/session.js

@@ -31,6 +31,7 @@ import { getThreadStore } from './threads/store.js';
 import { createIntentClassifier } from './router/intent-classifier.js';
 import { initInputQueueStore } from './input-queue/store.js';
 import { createDispatcher } from './pipeline/dispatcher.js';
+import { ensureDefaultGroupIfEmpty } from './groups/group-crud.js';
 import { join } from 'path';
 import { existsSync as existsSyncSafe, readFileSync as readFileSyncSafe } from 'fs';
 
@@ -164,6 +165,20 @@ export async function loadSession(options = {}) {
     idleArchiveDays: config.unify?.autoArchiveIdleDays ?? 0,
   });
 
+  // ─── 5c. D1 first-boot seed (task-334m) ─────────────────
+  //         When no groups exist on disk AND we're not in read-only mode,
+  //         seed a default group with roster = all VPs in the library,
+  //         defaultVpId = alphabetically first. Idempotent — no-op when
+  //         any group already exists. Never throws; failure logs a warning
+  //         so session load always succeeds.
+  if (!config._readOnly) {
+    try {
+      ensureDefaultGroupIfEmpty(yeaftDir);
+    } catch (err) {
+      console.warn(`[Yeaft] ensureDefaultGroupIfEmpty failed: ${err?.message || err}`);
+    }
+  }
+
   // ─── 6. Load skills ────────────────────────────────────
   let skillManager;
   if (skipSkills) {

package/unify/web-bridge.js

@@ -33,6 +33,16 @@ import {
   handleUnifyUserMemoryWrite as _handleUnifyUserMemoryWrite,
   handleUnifyUserMemoryRemove as _handleUnifyUserMemoryRemove,
 } from './user-memory.js';
+import {
+  GroupCrudError,
+  createGroupFromSpec,
+  renameGroup,
+  archiveGroup,
+  addMember,
+  removeMember,
+  setGroupDefaultVp,
+  snapshotGroups,
+} from './groups/group-crud.js';
 
 /** @type {import('./session.js').Session | null} */
 let session = null;
@@ -253,6 +263,151 @@ export function handleUnifyVpRead(msg) {
   sendVpCrudResult({ op: 'read', requestId, ok: true, vpId, vp });
 }
 
+/**
+ * task-334m: Group CRUD wired to WS events (§Δ10 334m + R6 §Δ31.2).
+ *
+ * Message shapes (wire):
+ *   unify_list_groups    { requestId? }
+ *   unify_create_group   { payload: {name, roster?, defaultVpId?}, requestId? }
+ *   unify_rename_group   { groupId, name, requestId? }
+ *   unify_archive_group  { groupId, requestId? }
+ *   unify_add_member     { groupId, vpId, requestId? }
+ *   unify_remove_member  { groupId, vpId, requestId? }
+ *   unify_set_default_vp { groupId, vpId, requestId? }
+ *
+ * Replies (sendUnifyEvent):
+ *   { type: 'group_crud_result', op, requestId, ok, group?, groups?, error?: {code, groupId?, message?} }
+ *
+ * Post-change broadcast (when meta mutates):
+ *   { type: 'group_roster_changed', groupId, roster, defaultVpId, name }
+ */
+function sendGroupCrudResult(payload) {
+  sendUnifyEvent({ type: 'group_crud_result', ...payload });
+}
+
+function sendGroupSnapshotBroadcast() {
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    if (!yeaftDir) return;
+    const groups = snapshotGroups(yeaftDir);
+    sendUnifyEvent({ type: 'group_list_updated', groups });
+  } catch (err) {
+    console.warn('[Unify] sendGroupSnapshotBroadcast failed:', err?.message || err);
+  }
+}
+
+function sendGroupRosterChanged(group) {
+  if (!group) return;
+  sendUnifyEvent({
+    type: 'group_roster_changed',
+    groupId: group.id,
+    name: group.name,
+    roster: group.roster,
+    defaultVpId: group.defaultVpId,
+  });
+}
+
+function groupErrorPayload(err) {
+  return {
+    code: err instanceof GroupCrudError ? err.code : 'unknown',
+    groupId: err && err.groupId,
+    message: err && err.message,
+  };
+}
+
+export function handleUnifyListGroups(msg) {
+  const requestId = msg && msg.requestId;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const groups = snapshotGroups(yeaftDir);
+    sendGroupCrudResult({ op: 'list', requestId, ok: true, groups });
+  } catch (err) {
+    sendGroupCrudResult({ op: 'list', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifyCreateGroup(msg) {
+  const requestId = msg && msg.requestId;
+  const payload = (msg && msg.payload) || {};
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const group = createGroupFromSpec(yeaftDir, payload);
+    sendGroupCrudResult({ op: 'create', requestId, ok: true, group });
+    sendGroupSnapshotBroadcast();
+  } catch (err) {
+    sendGroupCrudResult({ op: 'create', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifyRenameGroup(msg) {
+  const requestId = msg && msg.requestId;
+  const groupId = msg && msg.groupId;
+  const name = msg && msg.name;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const group = renameGroup(yeaftDir, groupId, name);
+    sendGroupCrudResult({ op: 'rename', requestId, ok: true, group });
+    sendGroupSnapshotBroadcast();
+  } catch (err) {
+    sendGroupCrudResult({ op: 'rename', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifyArchiveGroup(msg) {
+  const requestId = msg && msg.requestId;
+  const groupId = msg && msg.groupId;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const result = archiveGroup(yeaftDir, groupId);
+    sendGroupCrudResult({ op: 'archive', requestId, ok: true, groupId: result.groupId });
+    sendGroupSnapshotBroadcast();
+  } catch (err) {
+    sendGroupCrudResult({ op: 'archive', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifyAddMember(msg) {
+  const requestId = msg && msg.requestId;
+  const groupId = msg && msg.groupId;
+  const vpId = msg && msg.vpId;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const group = addMember(yeaftDir, groupId, vpId);
+    sendGroupCrudResult({ op: 'add_member', requestId, ok: true, group });
+    sendGroupRosterChanged(group);
+  } catch (err) {
+    sendGroupCrudResult({ op: 'add_member', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifyRemoveMember(msg) {
+  const requestId = msg && msg.requestId;
+  const groupId = msg && msg.groupId;
+  const vpId = msg && msg.vpId;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const group = removeMember(yeaftDir, groupId, vpId);
+    sendGroupCrudResult({ op: 'remove_member', requestId, ok: true, group });
+    sendGroupRosterChanged(group);
+  } catch (err) {
+    sendGroupCrudResult({ op: 'remove_member', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
+export function handleUnifySetDefaultVp(msg) {
+  const requestId = msg && msg.requestId;
+  const groupId = msg && msg.groupId;
+  const vpId = msg && msg.vpId;
+  try {
+    const yeaftDir = ctx.CONFIG?.yeaftDir;
+    const group = setGroupDefaultVp(yeaftDir, groupId, vpId);
+    sendGroupCrudResult({ op: 'set_default_vp', requestId, ok: true, group });
+    sendGroupRosterChanged(group);
+  } catch (err) {
+    sendGroupCrudResult({ op: 'set_default_vp', requestId, ok: false, error: groupErrorPayload(err) });
+  }
+}
+
 /**
  * task-318 rev-1 fix: install live-setter bridge between the session's
  * runtime handles (engineRegistry + threadStore) and `ctx.unifyRuntimeSettings`,
@@ -845,6 +1000,10 @@ export async function handleUnifyChat(msg) {
       // serverTime) so a freshly-connected client can restore inflight
       // status without waiting for the next engine event.
       sendThreadListSnapshot();
+      // task-334m: push initial groups snapshot so the Sidebar Groups
+      // section renders the full list immediately (including the D1
+      // default group seeded during session bootstrap).
+      sendGroupSnapshotBroadcast();
     }
 
     // ─── Per-call AbortController (task-320) ──
@@ -1318,6 +1477,8 @@ export async function handleUnifyLoadHistory(msg) {
   // mutation-delta stream; `thread_list_snapshot` is the single
   // authoritative "everything right now" payload.
   sendThreadListSnapshot();
+  // task-334m: replay groups snapshot so Sidebar Groups rebuilds on refresh.
+  sendGroupSnapshotBroadcast();
 
   const limit = msg.limit || 50;
   const messages = session.conversationStore.loadRecent(limit);