synomem 0.5.2 → 0.6.0

package/src/mcp/index.ts

@@ -321,6 +321,68 @@ export async function createSynomemMcpServer(
     },
   );
 
+  server.registerTool(
+    'synomem_agent_archive',
+    {
+      title: 'Archive an agent identity',
+      description:
+        'Administrative tool for archiving an agent identity, not deleting it. Everything it authored keeps its name and stays exactly as it is; the agent simply cannot act again until restored with synomem_agent_restore. Disabled by default so runtime agents cannot silently disable each other.',
+      inputSchema: z.object({
+        idOrAlias: z.string().min(1).describe('An agent ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ idOrAlias }) => {
+      try {
+        const capabilities = await client.capabilities();
+        if (!capabilities.administration.agentArchiveViaMcp) {
+          throw new SynomemError(
+            'POLICY_FORBIDDEN',
+            'Agent archiving via MCP is disabled by configuration.',
+          );
+        }
+        const profile = await client.agents.archive(idOrAlias);
+        return success(actor, `Archived agent ${profile.displayName} (${profile.id}).`, {
+          profile,
+        });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
+  server.registerTool(
+    'synomem_agent_restore',
+    {
+      title: 'Restore an archived agent identity',
+      description:
+        'Administrative tool for letting a previously archived agent act again, using the same agent ID it always had. Disabled by default alongside synomem_agent_archive.',
+      inputSchema: z.object({
+        idOrAlias: z.string().min(1).describe('An agent ID or alias, in any casing.'),
+      }),
+      outputSchema,
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true },
+    },
+    async ({ idOrAlias }) => {
+      try {
+        const capabilities = await client.capabilities();
+        if (!capabilities.administration.agentArchiveViaMcp) {
+          throw new SynomemError(
+            'POLICY_FORBIDDEN',
+            'Agent restoring via MCP is disabled by configuration.',
+          );
+        }
+        const profile = await client.agents.restore(idOrAlias);
+        return success(actor, `Restored agent ${profile.displayName} (${profile.id}).`, {
+          profile,
+        });
+      } catch (error) {
+        return failure(actor, error);
+      }
+    },
+  );
+
   server.registerTool(
     'synomem_agent_list',
     {
@@ -516,7 +578,7 @@ export async function createSynomemMcpServer(
     {
       title: 'List Synomem items',
       description:
-        'Discover a bounded page of compact kudos, memo, note, and task summaries. Full bodies, reasons, evidence, descriptions, source, and metadata are omitted; use synomem_get for one selected item.',
+        'Discover a bounded page of compact kudos, memo, note, post, task, and todo summaries. Pass kinds to narrow it: posts and todos are reachable only this way, because synomem_inbox holds only what another actor is waiting on. Full bodies, reasons, evidence, descriptions, source, and metadata are omitted; use synomem_get for one selected item.',
       inputSchema: itemListInputSchema,
       outputSchema,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -540,7 +602,7 @@ export async function createSynomemMcpServer(
     {
       title: 'Get one Synomem item',
       description:
-        'Read the full authorized record for one explicitly selected kudos, memo, note, or task ID.',
+        'Read the full authorized record for one explicitly selected kudos, memo, note, post, task, or todo ID.',
       inputSchema: z.object({ itemId: z.string().length(26) }),
       outputSchema,
       annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
@@ -584,7 +646,7 @@ export async function createSynomemMcpServer(
     {
       title: 'Review an agent inbox',
       description:
-        'Return compact pending kudos, unread memos, and open tasks for the configured agent. An agent may inspect only its own private items.',
+        'Return compact pending kudos, unread memos, and open tasks for the configured agent -- what another actor is waiting on it for, and nothing else. Notes, posts, and todos are never here, because nobody is waiting: reach those through synomem_list with kinds. An agent may inspect only its own private items.',
       inputSchema: z.object({
         limit: z.number().int().min(1).max(50).default(10),
         cursor: z.string().max(500).optional(),

package/src/mcp-server.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { parseArgs } from 'node:util';
 import { createConfiguredService } from './backend.js';
+import { resolveWorkspaceSelection } from './project.js';
 import { SynomemError } from './errors.js';
 import { actorSchema } from './schemas.js';
 import { startMcpServer } from './mcp/index.js';
@@ -12,6 +13,7 @@ const version = packageVersion();
 const { values } = parseArgs({
   options: {
     home: { type: 'string' },
+    workspace: { type: 'string' },
     'agent-id': { type: 'string' },
     'actor-id': { type: 'string' },
     'actor-kind': { type: 'string' },
@@ -59,12 +61,17 @@ async function resolveAgentActor(agentId: string, home?: string): Promise<ActorI
 }
 
 if (values.help) {
-  process.stdout.write(`synomem-mcp ${version}
+  process.stdout.write(
+    `synomem-mcp ${version}
 
 Actor-bound Synomem MCP server (stdio transport)
 
 Options:
   --home <path>          Storage root
+  --workspace <name>     Local workspace to act in. Defaults to the workspace
+                         named by .synomem/config.json in the working directory
+                         or any directory above it, then to SYNOMEM_WORKSPACE,
+                         then to the default workspace.
   --agent-id <id>        Bound agent, whose identity is read from Synomem
                          (or SYNOMEM_AGENT_ID)
   --actor-id <id>        Bound non-agent actor ID (or SYNOMEM_ACTOR_ID)
@@ -76,13 +83,33 @@ Options:
 
 Prefer --agent-id for an agent runtime: the display name and kind then come
 from the agent's profile instead of from whatever the harness was told to pass.
-`);
+`,
+  );
 } else if (values.version) {
   process.stdout.write(`${version}\n`);
 } else {
-  const agentId = values['agent-id'] ?? process.env.SYNOMEM_AGENT_ID;
+  /*
+   * The workspace is resolved from where the server was STARTED, which is what
+   * makes a project binding work at all.
+   *
+   * A harness launches this process in the repository it opened, so a
+   * `.synomem/config.json` there selects the workspace for the whole session
+   * without the harness knowing anything about workspaces, and without anybody
+   * repeating a flag. `--home` still wins, because it names a home outright
+   * rather than a workspace inside one.
+   */
+  const selection = values.home
+    ? undefined
+    : resolveWorkspaceSelection({
+        ...(values.workspace ? { flag: values.workspace } : {}),
+        env: process.env,
+      });
+  const home = values.home ?? selection?.home;
+
+  const agentId =
+    values['agent-id'] ?? process.env.SYNOMEM_AGENT_ID ?? selection?.actor ?? undefined;
   const actor = agentId
-    ? await resolveAgentActor(agentId, values.home)
+    ? await resolveAgentActor(agentId, home)
     : actorSchema.parse({
         id: values['actor-id'] ?? process.env.SYNOMEM_ACTOR_ID,
         kind: values['actor-kind'] ?? process.env.SYNOMEM_ACTOR_KIND,
@@ -91,6 +118,6 @@ from the agent's profile instead of from whatever the harness was told to pass.
 
   await startMcpServer({
     actor,
-    ...(values.home ? { home: values.home } : {}),
+    ...(home ? { home } : {}),
   });
 }

package/src/ports/projections.ts

@@ -3,4 +3,13 @@ import type { Awaitable } from './repository.js';
 
 export interface ProjectionWriter {
   syncAgent(agentId: string): Awaitable<ProjectionRebuildResult>;
+
+  /**
+   * Move an agent's projected directory when its handle changes.
+   *
+   * Optional: only a writer that owns a filesystem has a directory to move. A
+   * backend that keeps no projections implements nothing and the rename is
+   * simply a database change.
+   */
+  renameAgentDirectory?(previousHandle: string, nextHandle: string): Awaitable<void>;
 }

package/src/project.ts

@@ -0,0 +1,168 @@
+/**
+ * Per-project workspace selection.
+ *
+ * The goal is that opening an agent in a repository is enough: every note,
+ * memo, task, todo and post it writes lands in that repository's workspace,
+ * with nobody naming the workspace again for the rest of the session.
+ *
+ * That cannot be a command typed into a running session. The stdio MCP server
+ * is bound to a home and an actor when the harness launches it, so a later
+ * instruction has nothing to retarget. It also should not be one global
+ * "current workspace": two agents open in two repositories would fight over
+ * it, which is exactly the case this exists to serve.
+ *
+ * So it is a file in the project, found by walking up from the working
+ * directory — the same shape as `.git`, `.nvmrc` or `.npmrc`, and for the same
+ * reason: the directory somebody is working in is the thing that knows which
+ * project this is.
+ *
+ * `.synomem/config.json` holds a POINTER, never a store:
+ *
+ *     { "workspace": "lumina", "actor": "claude" }
+ *
+ * The database stays under the Synomem home. Putting one in the repository
+ * would mean an append-only event log inside somebody's git history, committed
+ * by accident the first time they ran `git add -A`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, parse, resolve } from 'node:path';
+import { resolveHome } from './config.js';
+import { z } from 'zod';
+import { SynomemError } from './errors.js';
+import { localWorkspaceHome, workspaceNameSchema } from './workspaces.js';
+
+export const PROJECT_DIRECTORY = '.synomem';
+export const PROJECT_CONFIG_FILE = 'config.json';
+
+export const projectConfigSchema = z.object({
+  /** The local workspace this project's records belong in. */
+  workspace: workspaceNameSchema.optional(),
+  /** The agent this project's records are written by, when it is always one. */
+  actor: z.string().trim().min(1).max(63).optional(),
+});
+
+export type ProjectConfig = z.infer<typeof projectConfigSchema>;
+
+export interface ProjectSelection extends ProjectConfig {
+  /** The directory whose `.synomem` was used, so tools can say where it came from. */
+  directory: string;
+}
+
+/**
+ * The nearest project configuration at or above `from`.
+ *
+ * Walking up stops at the filesystem root, and never treats the Synomem home
+ * itself as a project: `~/.synomem/config.json` is a real Synomem config with a
+ * different shape, and reading it as a project pointer would silently apply a
+ * home's settings to every command run anywhere under the home directory.
+ */
+export function findProjectSelection(
+  from: string = process.cwd(),
+  home?: string,
+): ProjectSelection | undefined {
+  const stopAt = parse(resolve(from)).root;
+  let directory = resolve(from);
+  for (;;) {
+    const candidate = join(directory, PROJECT_DIRECTORY, PROJECT_CONFIG_FILE);
+    // `<home>/config.json` is the home's own config, not a project pointer, and
+    // the home is never a project directory.
+    const isHome = home !== undefined && resolve(home) === join(directory, PROJECT_DIRECTORY);
+    if (!isHome && existsSync(candidate)) {
+      return { ...readProjectConfig(candidate), directory };
+    }
+    if (directory === stopAt) return undefined;
+    const parent = dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function readProjectConfig(path: string): ProjectConfig {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    throw new SynomemError('CONFIG_INVALID', `${path} is not readable JSON.`);
+  }
+  const parsed = projectConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new SynomemError(
+      'CONFIG_INVALID',
+      `${path} is not a valid Synomem project file: ${parsed.error.issues[0]?.message ?? 'unknown problem'}`,
+    );
+  }
+  return parsed.data;
+}
+
+/** Writes the pointer for a directory, creating `.synomem/` if needed. */
+export function writeProjectSelection(directory: string, config: ProjectConfig): string {
+  const parsed = projectConfigSchema.parse(config);
+  const folder = join(resolve(directory), PROJECT_DIRECTORY);
+  mkdirSync(folder, { recursive: true });
+  const path = join(folder, PROJECT_CONFIG_FILE);
+  writeFileSync(path, `${JSON.stringify(parsed, null, 2)}\n`);
+  return path;
+}
+
+/**
+ * Which workspace to act in, and as whom.
+ *
+ * One resolver, used by both the CLI and the stdio MCP server, so the two
+ * cannot disagree about precedence. Order, most specific first:
+ *
+ *   1. `--workspace` / `--actor` — said on this invocation
+ *   2. `SYNOMEM_WORKSPACE` / `SYNOMEM_ACTOR_ID` — set for this process
+ *   3. `.synomem/config.json` in the project, found by walking up from the
+ *      working directory
+ *   4. the root home, which is the default workspace
+ *
+ * The project file is third rather than first because a flag someone typed
+ * should always beat a file they may have forgotten is there.
+ */
+export function resolveWorkspaceSelection(input: {
+  flag?: string;
+  actorFlag?: string;
+  env?: NodeJS.ProcessEnv;
+  cwd?: string;
+  explicitRoot?: string;
+}): { home: string; workspace?: string; actor?: string; source: string } {
+  const env = input.env ?? process.env;
+  const root = resolveHome(input.explicitRoot);
+
+  if (input.flag) {
+    return {
+      home: localWorkspaceHome(input.flag, input.explicitRoot),
+      workspace: input.flag,
+      ...(input.actorFlag ? { actor: input.actorFlag } : {}),
+      source: 'the --workspace option',
+    };
+  }
+
+  const fromEnv = env.SYNOMEM_WORKSPACE?.trim();
+  if (fromEnv) {
+    return {
+      home: localWorkspaceHome(fromEnv, input.explicitRoot),
+      workspace: fromEnv,
+      ...((input.actorFlag ?? env.SYNOMEM_ACTOR_ID?.trim())
+        ? { actor: input.actorFlag ?? env.SYNOMEM_ACTOR_ID?.trim() }
+        : {}),
+      source: 'SYNOMEM_WORKSPACE',
+    };
+  }
+
+  const project = findProjectSelection(input.cwd ?? process.cwd(), root);
+  if (project?.workspace) {
+    return {
+      home: localWorkspaceHome(project.workspace, input.explicitRoot),
+      workspace: project.workspace,
+      ...((input.actorFlag ?? project.actor) ? { actor: input.actorFlag ?? project.actor } : {}),
+      source: join(project.directory, PROJECT_DIRECTORY, PROJECT_CONFIG_FILE),
+    };
+  }
+
+  return {
+    home: root,
+    ...((input.actorFlag ?? project?.actor) ? { actor: input.actorFlag ?? project?.actor } : {}),
+    source: 'the default workspace',
+  };
+}

package/src/projections.ts

@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, unlinkSync } from 'node:fs';
+import { existsSync, lstatSync, renameSync, unlinkSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { SynomemError } from './errors.js';
 import {
@@ -638,6 +638,43 @@ export class ProjectionManager implements ProjectionWriter {
     return { generated: generated.sort(), removed: removed.sort() };
   }
 
+  /**
+   * Move an agent's directory when its handle changes.
+   *
+   * Without this a rename left the old directory behind, and with it `NOTES.md`
+   * -- the one file in there that is the reader's rather than Synomem's, and so
+   * the one file a rebuild will never delete. The generated files moved to the
+   * new handle and the hand-written notes stayed at the old one.
+   *
+   * Moving rather than copy-and-delete, and moving rather than letting the
+   * rebuild sort it out, because a rename is a known identity change: the
+   * destination is new, so nothing is overwritten, and the human file arrives
+   * intact instead of being stranded.
+   */
+  renameAgentDirectory(previousHandle: string, nextHandle: string): void {
+    if (previousHandle === nextHandle) return;
+    this.storage.assertWritable();
+    const from = join(this.storage.home, previousHandle);
+    const to = join(this.storage.home, nextHandle);
+    assertNoSymlinkEscape(this.storage.home, from);
+    assertNoSymlinkEscape(this.storage.home, to);
+    if (!existsSync(from)) return;
+    // A directory already at the destination means the handle is in use, which
+    // the caller checks before reaching here. Refuse rather than merge.
+    if (existsSync(to)) {
+      throw new SynomemError(
+        'UNSAFE_PATH',
+        `Refusing to rename over an existing directory: ${nextHandle}`,
+      );
+    }
+    const stat = lstatSync(from);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) {
+      throw new SynomemError('UNSAFE_PATH', `Agent directory is not a plain directory: ${from}`);
+    }
+    renameSync(from, to);
+    this.storage.renameProjectionManifestPrefix(previousHandle, nextHandle);
+  }
+
   syncAgent(agentId: string): { generated: string[]; removed: string[] } {
     this.storage.assertWritable();
     const profile = this.storage.getAgent(agentId);

package/src/schemas.ts

@@ -9,6 +9,10 @@ const reservedIds = new Set([
   'synomem',
   'exports',
   'inbox',
+  // Named local workspaces live at `<home>/workspaces/<name>`, and projected
+  // agent directories at `<home>/<handle>` — so an agent called `workspaces`
+  // would collide with them.
+  'workspaces',
   'con',
   'prn',
   'aux',
@@ -131,18 +135,46 @@ export const evidenceSchema = z
     }
   });
 
-export const profileSchema = z.object({
-  /** Canonical, opaque and immutable. Events reference this, never the handle. */
-  id: agentIdSchema,
-  handle: agentHandleSchema,
-  displayName: z.string().trim().min(1).max(200),
-  aliases: z.array(agentAliasSchema).max(50).optional(),
-  description: z.string().trim().max(2000).optional(),
-  /** Archived agents keep their history and stop being able to act. */
-  status: z.enum(['active', 'archived']).default('active'),
-  createdAt: z.string().datetime({ offset: true }),
-  metadata: metadataSchema.optional(),
-});
+/**
+ * An agent profile, tolerant of the shape written before handles existed.
+ *
+ * Agents gained a mutable handle alongside their canonical ID in schema 7.
+ * Every `agent.created` event written before that carries an id and no handle,
+ * and those events are in an append-only log: rewriting them to add the field
+ * is precisely what such a log exists to prevent. So the READER widens instead.
+ *
+ * A missing handle means the record predates handles, and back then the ID *was*
+ * the name somebody typed — so the ID is not a placeholder here, it is the
+ * correct handle. Without this, one pre-7 agent made the compatibility check
+ * refuse the whole event stream, and every write in that workspace failed with
+ * `UNSUPPORTED_EVENT`.
+ */
+export const profileSchema = z.preprocess(
+  (value) => {
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      !Array.isArray(value) &&
+      !('handle' in value) &&
+      typeof (value as { id?: unknown }).id === 'string'
+    ) {
+      return { ...(value as Record<string, unknown>), handle: (value as { id: string }).id };
+    }
+    return value;
+  },
+  z.object({
+    /** Canonical, opaque and immutable. Events reference this, never the handle. */
+    id: agentIdSchema,
+    handle: agentHandleSchema,
+    displayName: z.string().trim().min(1).max(200),
+    aliases: z.array(agentAliasSchema).max(50).optional(),
+    description: z.string().trim().max(2000).optional(),
+    /** Archived agents keep their history and stop being able to act. */
+    status: z.enum(['active', 'archived']).default('active'),
+    createdAt: z.string().datetime({ offset: true }),
+    metadata: metadataSchema.optional(),
+  }),
+);
 
 /**
  * Creating an agent names a handle; the canonical ID is generated, never

package/src/service.ts

@@ -53,6 +53,7 @@ export interface SynomemServiceCapabilities {
   };
   administration: {
     agentCreationViaMcp: boolean;
+    agentArchiveViaMcp: boolean;
     rebuildViaMcp: boolean;
   };
   projections: {

package/src/storage.ts

@@ -2041,6 +2041,34 @@ export class SynomemStorage implements SynomemRepository {
     ).map((row) => row.path);
   }
 
+  /**
+   * Re-point manifest paths from one agent directory to another.
+   *
+   * The manifest records what Synomem generated and is what the stale-file
+   * cleanup consults. After a directory moves, entries still naming the old
+   * handle describe files that are no longer there, and the moved ones would
+   * look unaccounted for.
+   *
+   * Rewritten row by row rather than with a LIKE update: a manifest is small,
+   * and comparing an exact path prefix needs no thought about what characters
+   * a pattern would treat specially.
+   */
+  renameProjectionManifestPrefix(previousHandle: string, nextHandle: string): void {
+    const prefixes = [`${previousHandle}/`, `${previousHandle}\\`];
+    const rows = this.projectionManifestEntries().filter((entry) =>
+      prefixes.some((prefix) => entry.path.startsWith(prefix)),
+    );
+    if (!rows.length) return;
+    const remove = this.db().prepare('DELETE FROM projection_manifest WHERE path = ?');
+    const insert = this.db().prepare(
+      'INSERT OR REPLACE INTO projection_manifest(path, generated_at) VALUES (?, ?)',
+    );
+    for (const row of rows) {
+      remove.run(row.path);
+      insert.run(`${nextHandle}${row.path.slice(previousHandle.length)}`, row.generatedAt);
+    }
+  }
+
   /** The manifest with the time each path was written, newest first. */
   projectionManifestEntries(): { path: string; generatedAt: string }[] {
     return (

package/src/types.ts

@@ -770,6 +770,7 @@ export interface SynomemConfig {
   allowSelfAwards: boolean;
   allowCrossAgentTasks: boolean;
   allowAgentCreationViaMcp: boolean;
+  allowAgentArchiveViaMcp: boolean;
   allowRebuildViaMcp: boolean;
   includePrivateInStats: boolean;
   projection: {

package/src/workspaces.ts

@@ -0,0 +1,107 @@
+/**
+ * Local workspaces.
+ *
+ * On Synomem Cloud a workspace is a row, and isolation is enforced by the
+ * database: every record table carries `workspace_id`, has row-level security
+ * enabled, and every query runs with `synomem.workspace_id` set — so a query
+ * that forgets to filter returns nothing rather than another workspace's rows.
+ *
+ * SQLite has no row-level security, so the same schema locally would not buy
+ * the same guarantee: isolation would rest on every one of eighty query sites
+ * staying correct, with nothing underneath to catch a miss, and a miss would
+ * silently mix workspaces rather than fail. So a local workspace is a separate
+ * DATABASE — its own home, its own file. The filesystem does the isolating, and
+ * cross-workspace leakage stops being a thing anybody can write by accident.
+ *
+ * That is also why nothing downstream needs to know. A local workspace resolves
+ * to a home and a hosted one resolves to an id, both at the single seam in
+ * `backend.ts` that already chooses between the two backends. No domain code,
+ * CLI command or MCP tool can tell which it got.
+ */
+import { existsSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { SynomemError } from './errors.js';
+import { resolveHome } from './config.js';
+
+/**
+ * The directory named workspaces live under, relative to the root.
+ *
+ * `workspaces` is a reserved agent handle for exactly this reason: projected
+ * agent directories sit at `<home>/<handle>/`, so an agent allowed to call
+ * itself `workspaces` would collide with this.
+ */
+export const WORKSPACES_DIRECTORY = 'workspaces';
+
+/**
+ * The workspace whose home is the root itself.
+ *
+ * The root stays a complete Synomem home rather than becoming a container, so
+ * an existing install keeps its database exactly where it is and needs no
+ * migration. Named workspaces are added alongside it.
+ */
+export const DEFAULT_WORKSPACE = 'default';
+
+/** Same shape as an agent handle: a name somebody types, and a directory name. */
+export const workspaceNameSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(63)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'Use lowercase ASCII letters, digits, and hyphens')
+  .refine((name) => name !== WORKSPACES_DIRECTORY, 'Reserved workspace name');
+
+export interface LocalWorkspace {
+  name: string;
+  home: string;
+  /** False until `init` or the first write has created the store. */
+  initialized: boolean;
+}
+
+/**
+ * Where a named local workspace lives.
+ *
+ * The name is validated rather than trusted: it becomes a directory, so a value
+ * containing a separator or `..` would escape the root.
+ */
+export function localWorkspaceHome(name: string, explicitRoot?: string): string {
+  const root = resolveHome(explicitRoot);
+  if (name === DEFAULT_WORKSPACE) return root;
+  const parsed = workspaceNameSchema.safeParse(name);
+  if (!parsed.success) {
+    throw new SynomemError(
+      'INVALID_INPUT',
+      `Invalid workspace name: ${name}. ${parsed.error.issues[0]?.message ?? ''}`.trim(),
+    );
+  }
+  return join(root, WORKSPACES_DIRECTORY, parsed.data);
+}
+
+/**
+ * The local workspaces on this machine, discovered from disk.
+ *
+ * Read from the filesystem rather than a registry file, so a workspace cannot
+ * be listed and then turn out not to exist — and a directory copied in by hand
+ * is found without having to be registered.
+ */
+export function listLocalWorkspaces(explicitRoot?: string): LocalWorkspace[] {
+  const root = resolveHome(explicitRoot);
+  const found: LocalWorkspace[] = [
+    { name: DEFAULT_WORKSPACE, home: root, initialized: existsSync(join(root, 'config.json')) },
+  ];
+
+  const container = join(root, WORKSPACES_DIRECTORY);
+  if (!existsSync(container)) return found;
+  for (const entry of readdirSync(container, { withFileTypes: true })) {
+    // A symbolic link here would point the store outside the root.
+    if (!entry.isDirectory() || lstatSync(join(container, entry.name)).isSymbolicLink()) continue;
+    if (!workspaceNameSchema.safeParse(entry.name).success) continue;
+    const home = join(container, entry.name);
+    found.push({
+      name: entry.name,
+      home,
+      initialized: existsSync(join(home, 'config.json')),
+    });
+  }
+  return found.sort((left, right) => left.name.localeCompare(right.name));
+}