mercury-agent 0.16.0 → 0.16.2

package/src/profile/space-profile.ts

@@ -0,0 +1,780 @@
+/**
+ * Space profiles — one folder in the repo that owns every editorial rule for a
+ * space, plus the drift check that proves the live space still matches it.
+ *
+ * The rules for the `football-friends` space used to live in four places (two
+ * preferences, two task prompts, an empty `AGENTS.md`) and two of them
+ * disagreed about when the bot should stay silent. A profile folder gives them
+ * one home; `check` is what stops them drifting apart again.
+ *
+ * Everything here is pure apart from the two injected ports, so the whole
+ * apply/check surface is testable against a temp DB and a temp directory
+ * without a live project. The CLI in `scripts/space-profile.ts` is a thin
+ * wrapper: no logic lives there that is not exercised by a test.
+ */
+
+import { Database } from "bun:sqlite";
+import fs from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+/** A profile that could not be loaded, or an apply that must not proceed. */
+export class ProfileError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProfileError";
+  }
+}
+
+export interface ProfileTaskSpec {
+  /** Live `tasks.id`. Asserted to belong to the profile's space before a write. */
+  id: number;
+  /** Label for humans and for the drift report; never written to the database. */
+  name: string;
+  /** Absolute path the prompt was read from. */
+  promptPath: string;
+  prompt: string;
+}
+
+/**
+ * A file the profile puts in the space *once* and never touches again.
+ *
+ * The difference from `agentsMd` and the task prompts is the whole point: those
+ * are repo-owned and a hand edit is drift to be overwritten, while a seed hands
+ * ownership over on first write. The reporter's notebook — `MEMORY.md` and the
+ * episode notes under `knowledge/` — is written by the model mid-turn and by
+ * napkin's nightly distillation, so a profile that re-asserted its version would
+ * delete a day of memory on every `apply`.
+ */
+export interface ProfileSeedSpec {
+  /** Path inside the space directory. Validated at load, never escapes it. */
+  relPath: string;
+  /** Absolute path the seed content was read from. */
+  sourcePath: string;
+  content: string;
+}
+
+export interface SpaceProfile {
+  /** Absolute path of the profile folder. */
+  dir: string;
+  space: string;
+  agentsMd: string;
+  tasks: ProfileTaskSpec[];
+  removePreferences: string[];
+  extensionConfig: Record<string, string>;
+  workspaceRemove: string[];
+  workspaceSeed: ProfileSeedSpec[];
+}
+
+/** The database surface a profile needs. `Db` satisfies it structurally. */
+export interface ProfileStore {
+  /** Null when the space does not exist — `apply` must not invent one. */
+  getSpace(spaceId: string): { id: string } | null;
+  getTask(id: number): { id: number; spaceId: string; prompt: string } | null;
+  listTasks(spaceId?: string): {
+    id: number;
+    spaceId: string;
+    prompt: string;
+    name: string | null;
+    cron: string | null;
+    timezone: string | null;
+  }[];
+  updateTaskPrompt(id: number, prompt: string): boolean;
+  listSpacePreferences(spaceId: string): { key: string; value: string }[];
+  deleteSpacePreference(spaceId: string, key: string): boolean;
+  getSpaceConfig(spaceId: string, key: string): string | null;
+  listSpaceConfig(spaceId: string): { key: string; value: string }[];
+  setSpaceConfig(
+    spaceId: string,
+    key: string,
+    value: string,
+    updatedBy: string,
+  ): void;
+}
+
+/** The filesystem surface a profile needs, injected so tests can watch it. */
+export interface ProfileFs {
+  exists(p: string): boolean;
+  /** True only for an existing directory. */
+  isDirectory(p: string): boolean;
+  /** File contents, or null when the path does not exist. */
+  readText(p: string): string | null;
+  /** Write, creating parent directories. */
+  writeText(p: string, content: string): void;
+  /** Remove a file or a directory tree. */
+  removeRecursive(p: string): void;
+  /** Entry names directly under a directory; empty when it does not exist. */
+  listDir(p: string): string[];
+}
+
+export const nodeProfileFs: ProfileFs = {
+  exists: (p) => fs.existsSync(p),
+  isDirectory: (p) => {
+    try {
+      return fs.statSync(p).isDirectory();
+    } catch {
+      return false;
+    }
+  },
+  readText: (p) => (fs.existsSync(p) ? fs.readFileSync(p, "utf8") : null),
+  writeText: (p, content) => {
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, content, "utf8");
+  },
+  removeRecursive: (p) => fs.rmSync(p, { recursive: true, force: true }),
+  listDir: (p) => (fs.existsSync(p) ? fs.readdirSync(p).sort() : []),
+};
+
+export type Drift =
+  | { kind: "agents-md"; path: string; diff: string }
+  | { kind: "task-prompt"; taskId: number; name: string; diff: string }
+  | { kind: "task-missing"; taskId: number; name: string }
+  | {
+      kind: "task-foreign";
+      taskId: number;
+      name: string;
+      actualSpace: string;
+    }
+  | { kind: "preference"; key: string }
+  | { kind: "config"; key: string; expected: string; actual: string | null }
+  | { kind: "workspace"; relPath: string }
+  | { kind: "seed"; relPath: string; path: string };
+
+/**
+ * A task id that is absent or owned by another space aborts `apply` outright:
+ * writing a football prompt over another space's task is the one mistake here
+ * that reaches real people.
+ */
+export function isBlockingDrift(drift: Drift): boolean {
+  return drift.kind === "task-missing" || drift.kind === "task-foreign";
+}
+
+export function describeDrift(drift: Drift): string {
+  switch (drift.kind) {
+    case "agents-md":
+      return `AGENTS.md differs from the profile (${drift.path})\n${drift.diff}`;
+    case "task-prompt":
+      return `task ${drift.taskId} (${drift.name}) prompt differs from the profile\n${drift.diff}`;
+    case "task-missing":
+      return `task ${drift.taskId} (${drift.name}) does not exist`;
+    case "task-foreign":
+      return `task ${drift.taskId} (${drift.name}) belongs to space "${drift.actualSpace}"`;
+    case "preference":
+      return `preference "${drift.key}" is still set and the profile removes it`;
+    case "config":
+      return `config "${drift.key}" is ${drift.actual === null ? "unset" : `"${drift.actual}"`}, profile wants "${drift.expected}"`;
+    case "workspace":
+      return `workspace item "${drift.relPath}" is still present and the profile removes it`;
+    case "seed":
+      return `seed "${drift.relPath}" is missing and the profile seeds it (${drift.path})`;
+  }
+}
+
+/**
+ * Resolve a path inside the space directory, refusing anything that escapes it
+ * or names the directory itself. `workspace_remove` entries are deletions, and
+ * a `..` in one is the difference between tidying a workspace and deleting a
+ * space. `workspace_seed` targets get the same guard for the same reason from
+ * the other side: a seed is a write, and a `..` in one writes outside the space.
+ */
+export function assertSafeRelative(
+  relPath: string,
+  field = "workspace_remove",
+): void {
+  if (path.isAbsolute(relPath)) {
+    throw new ProfileError(`${field} entry must be relative, got "${relPath}"`);
+  }
+  const normalized = path.normalize(relPath);
+  if (normalized === "." || normalized === "") {
+    throw new ProfileError(
+      `${field} entry "${relPath}" names the space directory itself`,
+    );
+  }
+  if (normalized === ".." || normalized.startsWith(`..${path.sep}`)) {
+    throw new ProfileError(
+      `${field} entry "${relPath}" escapes the space directory`,
+    );
+  }
+}
+
+export function resolveInsideSpace(
+  spaceDir: string,
+  relPath: string,
+  field = "workspace_remove",
+): string {
+  assertSafeRelative(relPath, field);
+  return path.resolve(spaceDir, relPath);
+}
+
+/**
+ * Same shape the database enforces (`SPACE_ID_RE` in `src/storage/db.ts`).
+ * Duplicated rather than exported because the check here guards a different
+ * thing: `space` is a path segment in `resolveSpaceDir`, so an unvalidated
+ * value with `..` in it puts `apply` outside the project entirely — writing an
+ * `AGENTS.md` and running `removeRecursive` over whatever it finds there. A
+ * profile with no `tasks:` has nothing else standing in the way.
+ */
+const SPACE_ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new ProfileError(
+      `config.yaml: "${field}" must be a non-empty string`,
+    );
+  }
+  return value;
+}
+
+function optionalStringArray(value: unknown, field: string): string[] {
+  if (value === undefined || value === null) return [];
+  if (!Array.isArray(value)) {
+    throw new ProfileError(`config.yaml: "${field}" must be a list`);
+  }
+  return value.map((entry, i) => requireString(entry, `${field}[${i}]`));
+}
+
+export function loadProfile(
+  dir: string,
+  fsPort: ProfileFs = nodeProfileFs,
+): SpaceProfile {
+  const profileDir = path.resolve(dir);
+  const configPath = path.join(profileDir, "config.yaml");
+  const rawConfig = fsPort.readText(configPath);
+  if (rawConfig === null) {
+    throw new ProfileError(`no config.yaml in ${profileDir}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(rawConfig);
+  } catch (e) {
+    throw new ProfileError(
+      `config.yaml is not valid YAML: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    throw new ProfileError("config.yaml must be a mapping");
+  }
+  const cfg = parsed as Record<string, unknown>;
+
+  const space = requireString(cfg.space, "space");
+  if (!SPACE_ID_RE.test(space)) {
+    throw new ProfileError(
+      `config.yaml: "space" must match ${SPACE_ID_RE.source}, got "${space}"`,
+    );
+  }
+
+  const agentsMdRel = requireString(cfg.agents_md, "agents_md");
+  const agentsMdPath = path.resolve(profileDir, agentsMdRel);
+  const agentsMd = fsPort.readText(agentsMdPath);
+  if (agentsMd === null) {
+    throw new ProfileError(`agents_md file not found: ${agentsMdPath}`);
+  }
+
+  // A bare `tasks:` parses as null; that is an empty list, not an error.
+  const rawTasks = cfg.tasks ?? [];
+  if (!Array.isArray(rawTasks)) {
+    throw new ProfileError('config.yaml: "tasks" must be a list');
+  }
+  const seenIds = new Set<number>();
+  const tasks: ProfileTaskSpec[] = rawTasks.map((entry, i) => {
+    if (typeof entry !== "object" || entry === null) {
+      throw new ProfileError(`config.yaml: tasks[${i}] must be a mapping`);
+    }
+    const t = entry as Record<string, unknown>;
+    if (typeof t.id !== "number" || !Number.isInteger(t.id)) {
+      throw new ProfileError(`config.yaml: tasks[${i}].id must be an integer`);
+    }
+    if (seenIds.has(t.id)) {
+      throw new ProfileError(`config.yaml: task id ${t.id} listed twice`);
+    }
+    seenIds.add(t.id);
+    const promptRel = requireString(t.prompt, `tasks[${i}].prompt`);
+    const promptPath = path.resolve(profileDir, promptRel);
+    const prompt = fsPort.readText(promptPath);
+    if (prompt === null) {
+      throw new ProfileError(`task prompt file not found: ${promptPath}`);
+    }
+    return {
+      id: t.id,
+      name: typeof t.name === "string" ? t.name : String(t.id),
+      promptPath,
+      prompt,
+    };
+  });
+
+  const rawExtCfg = cfg.extension_config;
+  if (
+    rawExtCfg !== undefined &&
+    rawExtCfg !== null &&
+    (typeof rawExtCfg !== "object" || Array.isArray(rawExtCfg))
+  ) {
+    throw new ProfileError('config.yaml: "extension_config" must be a mapping');
+  }
+  const extensionConfig: Record<string, string> = {};
+  for (const [key, value] of Object.entries(
+    (rawExtCfg ?? {}) as Record<string, unknown>,
+  )) {
+    // Values are compared against TEXT columns, so a YAML `true` or `2000`
+    // would report drift against the string the database holds forever.
+    if (typeof value !== "string") {
+      throw new ProfileError(
+        `config.yaml: extension_config."${key}" must be a quoted string, got ${typeof value}`,
+      );
+    }
+    extensionConfig[key] = value;
+  }
+
+  const workspaceRemove = optionalStringArray(
+    cfg.workspace_remove,
+    "workspace_remove",
+  );
+  // Validate at load time so a bad entry fails before anything is written.
+  for (const rel of workspaceRemove) assertSafeRelative(rel);
+
+  const rawSeed = cfg.workspace_seed;
+  if (
+    rawSeed !== undefined &&
+    rawSeed !== null &&
+    (typeof rawSeed !== "object" || Array.isArray(rawSeed))
+  ) {
+    throw new ProfileError(
+      'config.yaml: "workspace_seed" must be a mapping of target path -> source file',
+    );
+  }
+  const workspaceSeed: ProfileSeedSpec[] = [];
+  for (const [relPath, rawSource] of Object.entries(
+    (rawSeed ?? {}) as Record<string, unknown>,
+  )) {
+    const sourceRel = requireString(rawSource, `workspace_seed."${relPath}"`);
+    assertSafeRelative(relPath, "workspace_seed");
+    const sourcePath = path.resolve(profileDir, sourceRel);
+    const content = fsPort.readText(sourcePath);
+    // Same rule as a task prompt: a missing source is an error, never an empty
+    // seed. A seed is written once, so a silently empty one is permanent.
+    if (content === null) {
+      throw new ProfileError(`seed source file not found: ${sourcePath}`);
+    }
+    workspaceSeed.push({ relPath, sourcePath, content });
+  }
+
+  // A path that is both seeded and removed has no defined outcome — apply
+  // would write it and delete it in the same run, or leave the result to the
+  // order of two unrelated lists. Reject the manifest instead of picking one.
+  // `knowledge/` and `knowledge` must compare equal, or a trailing slash on one
+  // side is enough to walk past the check. Case is folded too: this only ever
+  // rejects a manifest, so erring towards "these might be the same path" costs
+  // an author one rename and catches the Windows case.
+  const normalizeRel = (p: string) =>
+    path
+      .normalize(p)
+      .replace(/[\\/]+$/, "")
+      .toLowerCase();
+  for (const seed of workspaceSeed) {
+    const seedNorm = normalizeRel(seed.relPath);
+    for (const rel of workspaceRemove) {
+      const removeNorm = normalizeRel(rel);
+      if (
+        seedNorm === removeNorm ||
+        seedNorm.startsWith(`${removeNorm}${path.sep}`) ||
+        seedNorm.startsWith(`${removeNorm}/`)
+      ) {
+        throw new ProfileError(
+          `config.yaml: "${seed.relPath}" is seeded by workspace_seed and removed by workspace_remove ("${rel}")`,
+        );
+      }
+    }
+  }
+
+  return {
+    dir: profileDir,
+    space,
+    agentsMd,
+    tasks,
+    removePreferences: optionalStringArray(
+      cfg.remove_preferences,
+      "remove_preferences",
+    ),
+    extensionConfig,
+    workspaceRemove,
+    workspaceSeed,
+  };
+}
+
+/** `<project>/<dataDir>/spaces/<space>` — where the container mounts from. */
+export function resolveSpaceDir(
+  projectDir: string,
+  dataDir: string,
+  space: string,
+): string {
+  return path.resolve(projectDir, dataDir, "spaces", space);
+}
+
+/**
+ * `<project>/<dataDir>/state.db`, refusing a path that does not already hold a
+ * database. `Db`'s constructor creates the file and its directory on open, so
+ * without this check a mistyped `--project` would quietly leave an empty,
+ * migrated `state.db` behind and report every task as missing.
+ *
+ * `path.resolve`, not `path.join`: an absolute `dataDir` must replace the
+ * project dir, which is how the bot itself resolves it.
+ */
+export function locateDatabase(
+  projectDir: string,
+  dataDir: string,
+  fsPort: ProfileFs = nodeProfileFs,
+): string {
+  const dbPath = path.resolve(projectDir, dataDir, "state.db");
+  if (!fsPort.exists(dbPath)) {
+    throw new ProfileError(
+      `no database at ${dbPath} — is --project a Mercury project directory?`,
+    );
+  }
+  return dbPath;
+}
+
+/**
+ * Copy the live database with `VACUUM INTO`, which is safe against a running
+ * bot: it takes an ordinary read transaction on the WAL file and writes a
+ * consistent, compacted copy. Refuses to overwrite, so a second backup into the
+ * same path is an error rather than a silent replacement of the one that
+ * mattered.
+ */
+export function backupDatabase(
+  dbPath: string,
+  outPath: string,
+  fsPort: ProfileFs = nodeProfileFs,
+): void {
+  const resolvedOut = path.resolve(outPath);
+  if (fsPort.exists(resolvedOut)) {
+    throw new ProfileError(`backup target already exists: ${resolvedOut}`);
+  }
+  fs.mkdirSync(path.dirname(resolvedOut), { recursive: true });
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    // A parameter is not allowed in VACUUM INTO; escape by doubling quotes.
+    db.exec(`VACUUM INTO '${resolvedOut.replace(/'/g, "''")}'`);
+  } finally {
+    db.close();
+  }
+}
+
+function requireSpace(store: ProfileStore, space: string): void {
+  if (store.getSpace(space) === null) {
+    throw new ProfileError(
+      `space "${space}" does not exist in this database — nothing here will create one`,
+    );
+  }
+}
+
+export function agentsMdPathFor(spaceDir: string): string {
+  return path.join(spaceDir, "AGENTS.md");
+}
+
+/**
+ * Minimal unified diff over lines. The inputs are whole prompt files of a few
+ * hundred lines at most, so the quadratic LCS table is cheaper than a
+ * dependency.
+ */
+export function unifiedDiff(
+  expected: string,
+  actual: string,
+  label: string,
+): string {
+  const a = actual.split("\n");
+  const b = expected.split("\n");
+  const lcs: number[][] = Array.from({ length: a.length + 1 }, () =>
+    new Array<number>(b.length + 1).fill(0),
+  );
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      lcs[i][j] =
+        a[i] === b[j]
+          ? lcs[i + 1][j + 1] + 1
+          : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+
+  const out: string[] = [`--- live/${label}`, `+++ profile/${label}`];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      out.push(`  ${a[i]}`);
+      i++;
+      j++;
+    } else if (lcs[i + 1][j] >= lcs[i][j + 1]) {
+      out.push(`- ${a[i]}`);
+      i++;
+    } else {
+      out.push(`+ ${b[j]}`);
+      j++;
+    }
+  }
+  while (i < a.length) out.push(`- ${a[i++]}`);
+  while (j < b.length) out.push(`+ ${b[j++]}`);
+  return out.join("\n");
+}
+
+/**
+ * Everything the live space does not match the profile on. Never writes.
+ *
+ * A missing `AGENTS.md` reads as an empty file rather than an error: that is
+ * exactly the state this feature exists to fix, and it should show as drift,
+ * not as a crash.
+ */
+export function diffProfile(
+  profile: SpaceProfile,
+  store: ProfileStore,
+  spaceDir: string,
+  fsPort: ProfileFs = nodeProfileFs,
+): Drift[] {
+  // `space_config` has no foreign key to `spaces`, so without this a typo'd
+  // space id with no tasks listed would apply cleanly to a space that is not
+  // there: a new directory, a few config rows, exit 0.
+  requireSpace(store, profile.space);
+
+  const drifts: Drift[] = [];
+
+  const agentsPath = agentsMdPathFor(spaceDir);
+  const liveAgents = fsPort.readText(agentsPath) ?? "";
+  if (liveAgents !== profile.agentsMd) {
+    drifts.push({
+      kind: "agents-md",
+      path: agentsPath,
+      diff: unifiedDiff(profile.agentsMd, liveAgents, "AGENTS.md"),
+    });
+  }
+
+  for (const task of profile.tasks) {
+    const row = store.getTask(task.id);
+    if (!row) {
+      drifts.push({ kind: "task-missing", taskId: task.id, name: task.name });
+      continue;
+    }
+    if (row.spaceId !== profile.space) {
+      drifts.push({
+        kind: "task-foreign",
+        taskId: task.id,
+        name: task.name,
+        actualSpace: row.spaceId,
+      });
+      continue;
+    }
+    if (row.prompt !== task.prompt) {
+      drifts.push({
+        kind: "task-prompt",
+        taskId: task.id,
+        name: task.name,
+        diff: unifiedDiff(task.prompt, row.prompt, `task-${task.id}`),
+      });
+    }
+  }
+
+  const livePrefs = new Set(
+    store.listSpacePreferences(profile.space).map((p) => p.key),
+  );
+  for (const key of profile.removePreferences) {
+    if (livePrefs.has(key)) drifts.push({ kind: "preference", key });
+  }
+
+  for (const [key, expected] of Object.entries(profile.extensionConfig)) {
+    const actual = store.getSpaceConfig(profile.space, key);
+    if (actual !== expected) {
+      drifts.push({ kind: "config", key, expected, actual });
+    }
+  }
+
+  for (const rel of profile.workspaceRemove) {
+    if (fsPort.exists(resolveInsideSpace(spaceDir, rel))) {
+      drifts.push({ kind: "workspace", relPath: rel });
+    }
+  }
+
+  // Absence is the only seed drift there is. A seeded file that has since been
+  // edited — by the model mid-turn, by napkin's nightly distillation, by hand —
+  // is the file doing its job, so it is deliberately not compared. Seeds come
+  // last so that on a first apply they are written after `workspace_remove` has
+  // finished deleting, rather than into a directory about to be removed.
+  for (const seed of profile.workspaceSeed) {
+    const target = resolveInsideSpace(spaceDir, seed.relPath, "workspace_seed");
+    // A directory where the seed file should be is not "present": the seed can
+    // never be written there, and reporting nothing would leave `check` green
+    // over a notebook that does not exist. Fail loudly instead.
+    if (fsPort.isDirectory(target)) {
+      throw new ProfileError(
+        `seed target "${seed.relPath}" is a directory, not a file (${target})`,
+      );
+    }
+    if (!fsPort.exists(target)) {
+      drifts.push({ kind: "seed", relPath: seed.relPath, path: target });
+    }
+  }
+
+  return drifts;
+}
+
+export interface ApplyOptions {
+  dryRun?: boolean;
+  updatedBy?: string;
+}
+
+export interface ApplyChange {
+  kind: Drift["kind"];
+  detail: string;
+}
+
+/**
+ * Bring the live space in line with the profile. Idempotent: a second call
+ * finds no drift and changes nothing.
+ *
+ * Aborts before the first write if any configured task id is missing or owned
+ * by another space, so a stale `config.yaml` cannot half-apply.
+ */
+export function applyProfile(
+  profile: SpaceProfile,
+  store: ProfileStore,
+  spaceDir: string,
+  fsPort: ProfileFs = nodeProfileFs,
+  options: ApplyOptions = {},
+): ApplyChange[] {
+  const dryRun = options.dryRun === true;
+  const updatedBy = options.updatedBy ?? "space-profile";
+
+  const drifts = diffProfile(profile, store, spaceDir, fsPort);
+  const blocking = drifts.filter(isBlockingDrift);
+  if (blocking.length > 0) {
+    throw new ProfileError(
+      `refusing to apply — ${blocking.length} task id(s) do not belong to space "${profile.space}":\n` +
+        blocking.map((d) => `  - ${describeDrift(d)}`).join("\n"),
+    );
+  }
+
+  const changes: ApplyChange[] = [];
+  for (const drift of drifts) {
+    switch (drift.kind) {
+      case "agents-md": {
+        const target = agentsMdPathFor(spaceDir);
+        if (!dryRun) fsPort.writeText(target, profile.agentsMd);
+        changes.push({ kind: drift.kind, detail: `write ${target}` });
+        break;
+      }
+      case "task-prompt": {
+        const task = profile.tasks.find((t) => t.id === drift.taskId);
+        // diffProfile only emits this for a task that is in the profile.
+        if (!task) throw new ProfileError(`no profile task ${drift.taskId}`);
+        if (!dryRun && !store.updateTaskPrompt(task.id, task.prompt)) {
+          throw new ProfileError(
+            `task ${task.id} vanished between check and write`,
+          );
+        }
+        changes.push({
+          kind: drift.kind,
+          detail: `set prompt of task ${task.id} (${task.name})`,
+        });
+        break;
+      }
+      case "preference": {
+        if (!dryRun) store.deleteSpacePreference(profile.space, drift.key);
+        changes.push({
+          kind: drift.kind,
+          detail: `delete preference ${drift.key}`,
+        });
+        break;
+      }
+      case "config": {
+        if (!dryRun) {
+          store.setSpaceConfig(
+            profile.space,
+            drift.key,
+            drift.expected,
+            updatedBy,
+          );
+        }
+        changes.push({
+          kind: drift.kind,
+          detail: `set ${drift.key} = ${drift.expected}`,
+        });
+        break;
+      }
+      case "workspace": {
+        const target = resolveInsideSpace(spaceDir, drift.relPath);
+        if (!dryRun) fsPort.removeRecursive(target);
+        changes.push({ kind: drift.kind, detail: `remove ${target}` });
+        break;
+      }
+      case "seed": {
+        const seed = profile.workspaceSeed.find(
+          (s) => s.relPath === drift.relPath,
+        );
+        // diffProfile only emits this for a seed that is in the profile.
+        if (!seed) throw new ProfileError(`no profile seed ${drift.relPath}`);
+        if (!dryRun) fsPort.writeText(drift.path, seed.content);
+        changes.push({ kind: drift.kind, detail: `seed ${drift.path}` });
+        break;
+      }
+      case "task-missing":
+      case "task-foreign":
+        throw new ProfileError("blocking drift reached the write loop");
+    }
+  }
+
+  return changes;
+}
+
+export interface LiveDump {
+  space: string;
+  agentsMdPath: string;
+  agentsMd: string | null;
+  tasks: {
+    id: number;
+    name: string | null;
+    cron: string | null;
+    timezone: string | null;
+    prompt: string;
+  }[];
+  preferences: { key: string; value: string }[];
+  config: { key: string; value: string }[];
+  workspaceEntries: string[];
+}
+
+/**
+ * Read-only snapshot of every layer a profile owns, for the ops step that runs
+ * before the first apply.
+ *
+ * `taskIds` narrows the dump to the tasks a profile names. Passing an empty
+ * list dumps *every* task in the space — that is the point of the no-profile
+ * form (`dump --project <dir> --space <id>`), which is what you run before a
+ * profile exists, and which would otherwise print nothing.
+ */
+export function dumpLive(
+  space: string,
+  store: ProfileStore,
+  spaceDir: string,
+  taskIds: number[],
+  fsPort: ProfileFs = nodeProfileFs,
+): LiveDump {
+  requireSpace(store, space);
+  const agentsMdPath = agentsMdPathFor(spaceDir);
+  const wanted = new Set(taskIds);
+  const tasks = store
+    .listTasks(space)
+    .filter((t) => t.spaceId === space)
+    .filter((t) => wanted.size === 0 || wanted.has(t.id))
+    .map((t) => ({
+      id: t.id,
+      name: t.name,
+      cron: t.cron,
+      timezone: t.timezone,
+      prompt: t.prompt,
+    }));
+  return {
+    space,
+    agentsMdPath,
+    agentsMd: fsPort.readText(agentsMdPath),
+    tasks,
+    preferences: store.listSpacePreferences(space),
+    config: store.listSpaceConfig(space),
+    workspaceEntries: fsPort.listDir(spaceDir),
+  };
+}