@intentius/chant 0.124.31 → 0.124.32

package/src/ts-loader.test.ts

@@ -1,7 +1,9 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
 import { join, sep } from "node:path";
 import { pathToFileURL } from "node:url";
 import { describe, expect, test } from "vitest";
-import { chantSourceDir, ensureTypeScriptLoader } from "./ts-loader";
+import { chantPackageSourceTarget, chantSourceDir, lexiconCompiledTwin, ensureTypeScriptLoader, ensureTypeScriptLoaderFor, typeScriptLoaderPending } from "./ts-loader";
 
 describe("ts-loader (#3878)", () => {
   const pkg = join(sep, "x", "node_modules", "@intentius", "chant");
@@ -20,4 +22,90 @@ describe("ts-loader (#3878)", () => {
   test("from source, the TypeScript loader is already there and nothing is registered", () => {
     expect(ensureTypeScriptLoader()).toBe(false);
   });
+
+  test("from source, no module asks for the loader (#3981)", () => {
+    expect(typeScriptLoaderPending()).toBe(false);
+    expect(ensureTypeScriptLoaderFor("/p/src/index.ts")).toBe(false);
+    expect(ensureTypeScriptLoaderFor("/p/dist/index.js")).toBe(false);
+  });
+
+  test("compiled, a JavaScript module leaves tsx unregistered (#3981)", () => {
+    const STATE = Symbol.for("chant.compiledCli");
+    const global = globalThis as { [STATE]?: { tsx: boolean } };
+    global[STATE] = { tsx: false };
+    try {
+      expect(typeScriptLoaderPending()).toBe(true);
+      expect(ensureTypeScriptLoaderFor("file:///p/dist/index.js")).toBe(false);
+      expect(ensureTypeScriptLoaderFor("/p/dist/meta.json")).toBe(false);
+      expect(global[STATE]).toEqual({ tsx: false });
+      global[STATE] = { tsx: true };
+      expect(typeScriptLoaderPending()).toBe(false);
+      expect(ensureTypeScriptLoaderFor("/p/src/index.ts")).toBe(true);
+    } finally {
+      delete global[STATE];
+    }
+  });
+});
+
+describe("chantPackageSourceTarget (#3981)", () => {
+  test("resolves a symlinked lexicon's root and pattern exports to their development source, by real path", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-source-target-")));
+    try {
+      const lexicon = join(root, "lexicons", "demo");
+      mkdirSync(join(lexicon, "src", "generated"), { recursive: true });
+      writeFileSync(join(lexicon, "src", "index.ts"), "");
+      writeFileSync(join(lexicon, "src", "generated", "index.ts"), "");
+      writeFileSync(
+        join(lexicon, "package.json"),
+        JSON.stringify({
+          name: "@intentius/chant-lexicon-demo",
+          exports: {
+            ".": { development: "./src/index.ts", types: "./dist/index.d.ts", default: "./dist/index.js" },
+            "./*": { development: "./src/*.ts", types: "./dist/*.d.ts", default: "./dist/*.js" },
+            "./meta": "./dist/meta.json",
+          },
+        }),
+      );
+      mkdirSync(join(root, "project", "node_modules", "@intentius"), { recursive: true });
+      symlinkSync(lexicon, join(root, "project", "node_modules", "@intentius", "chant-lexicon-demo"), "dir");
+      mkdirSync(join(root, "project", "src"));
+      const parent = join(root, "project", "src", "infra.ts");
+
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo", parent)).toBe(join(lexicon, "src", "index.ts"));
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/generated/index", parent)).toBe(join(lexicon, "src", "generated", "index.ts"));
+      // No development condition, a missing file, another scope or an absent package: left to Node.
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/meta", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-demo/missing", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@other/chant-lexicon-demo", parent)).toBeUndefined();
+      expect(chantPackageSourceTarget("@intentius/chant-lexicon-absent", parent)).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("lexiconCompiledTwin (#3981)", () => {
+  test("points a lexicon's src/*.ts at its dist/*.js when that exists, and nothing else", () => {
+    const root = realpathSync(mkdtempSync(join(tmpdir(), "chant-compiled-twin-")));
+    try {
+      const lexicon = join(root, "node_modules", "@intentius", "chant-lexicon-demo");
+      const other = join(root, "node_modules", "other");
+      for (const dir of [join(lexicon, "src", "generated"), join(lexicon, "dist", "generated"), join(other, "src"), join(other, "dist")]) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(join(lexicon, "package.json"), JSON.stringify({ name: "@intentius/chant-lexicon-demo" }));
+      writeFileSync(join(other, "package.json"), JSON.stringify({ name: "other" }));
+      for (const file of ["src/generated/index.ts", "dist/generated/index.js", "src/only-source.ts"]) writeFileSync(join(lexicon, file), "");
+      for (const file of ["src/index.ts", "dist/index.js"]) writeFileSync(join(other, file), "");
+      const url = (path: string) => pathToFileURL(path).href;
+
+      expect(lexiconCompiledTwin(url(join(lexicon, "src", "generated", "index.ts")))).toBe(url(join(lexicon, "dist", "generated", "index.js")));
+      expect(lexiconCompiledTwin(url(join(lexicon, "src", "only-source.ts")))).toBeUndefined();
+      expect(lexiconCompiledTwin(url(join(lexicon, "dist", "generated", "index.js")))).toBeUndefined();
+      expect(lexiconCompiledTwin(url(join(other, "src", "index.ts")))).toBeUndefined();
+      expect(lexiconCompiledTwin("node:fs")).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
 });

package/src/ts-loader.ts

@@ -18,13 +18,15 @@
  *
  * Run from source (the repository's `bin/chant` through tsx, vitest), this
  * module is itself TypeScript, the TypeScript loader is already there, and
- * both functions do nothing.
+ * both functions do nothing, except that {@link installCompiledCli} resolves
+ * chant's packages to their source (#3981, {@link installSourceResolution}).
  */
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import * as nodeModule from "node:module";
 import { dirname, join, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { isJavaScriptModule, moduleSourceDir } from "./module-source";
 
 // `module.registerHooks` (Node 22.15+, 24) is newer than the @types/node the
 // repository pins, so its shape is declared here.
@@ -57,11 +59,15 @@ function runsCompiled(): boolean {
 
 /**
  * Called once by the CLI's `main()`. Compiled, it records that TypeScript
- * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect; from
- * source it does nothing.
+ * loads lazily and installs the `src/*.ts` to `dist/*.js` redirect. From
+ * source it installs {@link installSourceResolution}.
  */
 export function installCompiledCli(): void {
-  if (!runsCompiled() || compiledState()) return;
+  if (!runsCompiled()) {
+    installSourceResolution();
+    return;
+  }
+  if (compiledState()) return;
   (globalThis as { [STATE]?: CompiledCliState })[STATE] = { tsx: false };
 
   const distDir = dirname(fileURLToPath(import.meta.url));
@@ -72,7 +78,10 @@ export function installCompiledCli(): void {
   registerHooks({
     resolve(specifier, context, nextResolve) {
       const result = nextResolve(specifier, context);
-      if (!result.url.startsWith(srcUrl)) return result;
+      if (!result.url.startsWith(srcUrl)) {
+        const twin = lexiconCompiledTwin(result.url);
+        return twin === undefined ? result : { ...result, url: twin, format: "module" };
+      }
       const path = result.url.slice(srcUrl.length).replace(/[?#].*$/, "");
       if (!path.endsWith(".ts") || path.endsWith(".d.ts")) return result;
       let target = compiled.get(path);
@@ -86,6 +95,144 @@ export function installCompiledCli(): void {
   });
 }
 
+/** Package directories by the directory a module sits in: a lexicon package's root, or null for any other package. */
+const lexiconRoots = new Map<string, string | null>();
+
+/** The lexicon package `dir` belongs to: the nearest directory up with a package.json, when it names a chant lexicon. */
+function lexiconRootOf(dir: string): string | undefined {
+  const seen: string[] = [];
+  let root: string | null = null;
+  for (let at = dir; ; ) {
+    const cached = lexiconRoots.get(at);
+    if (cached !== undefined) {
+      root = cached;
+      break;
+    }
+    seen.push(at);
+    const manifest = join(at, "package.json");
+    if (existsSync(manifest)) {
+      try {
+        const name = (JSON.parse(readFileSync(manifest, "utf-8")) as { name?: unknown }).name;
+        root = typeof name === "string" && name.startsWith("@intentius/chant-lexicon-") ? at : null;
+      } catch {
+        root = null;
+      }
+      break;
+    }
+    const parent = dirname(at);
+    if (parent === at) break;
+    at = parent;
+  }
+  for (const at of seen) lexiconRoots.set(at, root);
+  return root ?? undefined;
+}
+
+/**
+ * #3981 — the compiled module for a lexicon's `src/*.ts`: `<lexicon>/dist/*.js`
+ * when it exists, as a URL, else `undefined`. A lexicon ships both, and its
+ * exports name the compiled one; fold reads a composite from the source, and
+ * an import that source makes must land on the module the plugin and the
+ * project already loaded, with no TypeScript loader.
+ */
+export function lexiconCompiledTwin(url: string): string | undefined {
+  if (!url.startsWith("file:")) return undefined;
+  const path = fileURLToPath(url.replace(/[?#].*$/, ""));
+  if (!/\.[cm]?ts$/.test(path) || /\.d\.[cm]?ts$/.test(path) || !path.includes(`${sep}src${sep}`)) return undefined;
+  const root = lexiconRootOf(dirname(path));
+  if (root === undefined) return undefined;
+  const srcDir = join(root, "src") + sep;
+  if (!path.startsWith(srcDir)) return undefined;
+  const js = join(root, "dist", path.slice(srcDir.length)).replace(/\.([cm]?)ts$/, ".$1js");
+  return existsSync(js) ? pathToFileURL(js).href : undefined;
+}
+
+const SOURCE_RESOLUTION = Symbol.for("chant.sourceResolution");
+
+/**
+ * #3981 — the `development` target a chant package's `exports` give
+ * `specifier`, found from `parentPath`'s directory up through each
+ * `node_modules`, or `undefined` when there is none or its file does not
+ * exist. Reads exact keys and single-`*` patterns, the shapes chant's
+ * packages use; anything else is left to Node.
+ */
+export function chantPackageSourceTarget(specifier: string, parentPath: string): string | undefined {
+  const match = /^(@intentius\/chant(?:-[a-z0-9-]+)?)(\/.*)?$/.exec(specifier);
+  if (!match) return undefined;
+  const subpath = match[2] ? `.${match[2]}` : ".";
+  let dir = dirname(parentPath);
+  for (;;) {
+    const pkgDir = join(dir, "node_modules", match[1]!);
+    const manifest = join(pkgDir, "package.json");
+    if (existsSync(manifest)) {
+      let exportsField: unknown;
+      try {
+        exportsField = (JSON.parse(readFileSync(manifest, "utf-8")) as { exports?: unknown }).exports;
+      } catch {
+        return undefined;
+      }
+      if (!exportsField || typeof exportsField !== "object") return undefined;
+      const map = exportsField as Record<string, unknown>;
+      let entry: unknown = map[subpath];
+      let star: string | undefined;
+      if (entry === undefined) {
+        let best = "";
+        for (const key of Object.keys(map)) {
+          const at = key.indexOf("*");
+          if (at < 0 || key.indexOf("*", at + 1) >= 0) continue;
+          const prefix = key.slice(0, at);
+          const suffix = key.slice(at + 1);
+          if (!subpath.startsWith(prefix) || !subpath.endsWith(suffix) || subpath.length < key.length || prefix.length <= best.length) continue;
+          best = prefix;
+          entry = map[key];
+          star = subpath.slice(prefix.length, subpath.length - suffix.length);
+        }
+      }
+      const development = entry && typeof entry === "object" ? (entry as { development?: unknown }).development : undefined;
+      if (typeof development !== "string") return undefined;
+      const target = join(pkgDir, star === undefined ? development : development.split("*").join(star));
+      // Node keys a module by its real path, so a symlinked package must too.
+      return existsSync(target) ? realpathSync(target) : undefined;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/**
+ * #3981 — from source, resolve chant's own packages through their
+ * `development` export condition, as `node --conditions=development` (which
+ * the repository's `bin/chant` passes) would. A lexicon's `default` export is
+ * its compiled `dist/*.js`, which a checkout may not have built, or built from
+ * older source; `development` is its `src/*.ts`, which vitest, a project's
+ * tsconfig `paths` and fold's own resolution (`SOURCE_EXPORT_CONDITIONS`)
+ * pick. Without this, a CLI run from source by `node --import tsx` would load
+ * a plugin from `dist/` and fold the project against `src/`: two copies of the
+ * lexicon with their own classes.
+ *
+ * The hook resolves the specifier itself and short-circuits: conditions added
+ * to the context here do not reach tsx's resolver. Nothing is installed under
+ * vitest, whose resolver already adds the condition, or on a node without
+ * `module.registerHooks`.
+ */
+function installSourceResolution(): void {
+  // In a vitest worker (not a CLI it spawns, which inherits its environment), vite resolves.
+  if ("__vitest_worker__" in globalThis || typeof registerHooks !== "function") return;
+  const flags = globalThis as { [SOURCE_RESOLUTION]?: boolean };
+  if (flags[SOURCE_RESOLUTION]) return;
+  flags[SOURCE_RESOLUTION] = true;
+  registerHooks({
+    resolve(specifier, context, nextResolve) {
+      const parentURL = (context as { parentURL?: string } | undefined)?.parentURL;
+      if (specifier.startsWith("@intentius/chant") && parentURL?.startsWith("file:")) {
+        const target = chantPackageSourceTarget(specifier, fileURLToPath(parentURL));
+        if (target !== undefined) return { url: pathToFileURL(target).href, shortCircuit: true };
+      }
+      return nextResolve(specifier, context);
+    },
+  });
+}
+
 /**
  * Register tsx for the ESM and CommonJS loaders, once, before importing
  * anything that may be TypeScript. A no-op from source, where tsx (or vitest)
@@ -104,19 +251,39 @@ export function ensureTypeScriptLoader(): boolean {
   return true;
 }
 
+/**
+ * #3981 — register tsx only when the module about to be imported is not
+ * JavaScript. `pathOrUrl` is the resolved module, a path or a file URL. A
+ * compiled lexicon (`dist/*.js`) imports with plain node, so a command that
+ * loads only compiled modules never pays for tsx's hooks thread. A `.ts`
+ * module, or one with no extension, registers tsx as before. Returns what
+ * {@link ensureTypeScriptLoader} does, or whether tsx is already registered
+ * when the module is JavaScript.
+ */
+export function ensureTypeScriptLoaderFor(pathOrUrl: string): boolean {
+  if (!isJavaScriptModule(pathOrUrl)) return ensureTypeScriptLoader();
+  return compiledState()?.tsx ?? false;
+}
+
+/**
+ * #3981 — whether a caller about to import a module of unknown kind should
+ * resolve it first: true only in the compiled CLI before tsx is registered.
+ * From source, and once tsx is in, every module loads either way.
+ */
+export function typeScriptLoaderPending(): boolean {
+  const state = compiledState();
+  return state !== undefined && !state.tsx;
+}
+
 /**
  * The source directory for a module of chant's own: `dirname` of `moduleUrl`
  * from source, and the matching directory under `<package>/src` when the
  * module runs from `<package>/dist`. The sandbox drivers hand chant's own
  * modules to esbuild by path, and must name the TypeScript source the
  * project's own `@intentius/chant/*` imports resolve to. String arithmetic
- * only: no filesystem access, so it is safe inside a sandboxed child.
+ * only: no filesystem access, so it is safe inside a sandboxed child. The
+ * same mapping as {@link moduleSourceDir}, which lexicons use.
  */
 export function chantSourceDir(moduleUrl: string): string {
-  const dir = dirname(fileURLToPath(moduleUrl));
-  if (!moduleUrl.endsWith(".js")) return dir;
-  const marker = `${sep}dist${sep}`;
-  const at = (dir + sep).lastIndexOf(marker);
-  if (at < 0) return dir;
-  return dir.slice(0, at) + `${sep}src` + dir.slice(at + marker.length - 1);
+  return moduleSourceDir(moduleUrl);
 }

package/src/workspace/changes.test.ts

@@ -292,7 +292,7 @@ describe("the forward coverage check (#2773)", () => {
   });
 
   test("on a work branch, the range and the item come from the branch (an Op under changesCheckout)", async () => {
-    const tree = join(root, ".git", "chant-work", "W-001");
+    const tree = join(root, ".chant", "work", "W-001");
     git(root, "worktree", "add", "-q", "-b", "chant/work/W-001", tree, "HEAD");
     writeFiles(tree, { "app/lib/a.mjs": "export const a = 2;\n", "docs/readme.md": "# Docs, again\n" });
     git(tree, "add", "-A");

package/src/workspace/chant-migrations/fountain-retired-kinds.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, test } from "vitest";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { rewriteFountainFile } from "./fountain-retired-kinds";
+
+const fixture = JSON.parse(readFileSync(join(import.meta.dirname, "../__fixtures__/studio-template-84c8b21.json"), "utf-8")) as { files: Record<string, string> };
+const team = fixture.files["delivery/agents/team.ts"]!;
+
+describe("fountain-retired-kinds (#3987)", () => {
+  test("the studio template's team.ts loses its Teammates, Schedules and persistent sandbox, and keeps its Agents", () => {
+    const r = rewriteFountainFile("delivery/agents/team.ts", team)!;
+    expect(r.conflict).toBeUndefined();
+    expect(r.text).toContain('import { Agent, Environment, Vault } from "@intentius/chant-lexicon-fountain";');
+    expect(r.text).not.toMatch(/new (Teammate|Schedule)\(|sandbox_mode|nightlyMeta|Teammates below/);
+    for (const agent of ["formalizer", "splitter", "builderSmall", "builderMedium", "builderLarge", "dispatcher"]) expect(r.text).toContain(`export const ${agent} = new Agent({`);
+    expect(r.text.endsWith("});\n")).toBe(true);
+    expect(r.notMoved.map((n) => n.what)).toEqual([
+      'the Schedule nightly (cron "0 3 * * *") in delivery/agents/team.ts',
+      'the Schedule factoryDispatch (cron "*/15 * * * *") in delivery/agents/team.ts',
+    ]);
+    expect(rewriteFountainFile("delivery/agents/team.ts", r.text)).toBeNull();
+  });
+
+  test("a removed declaration the file still uses is a conflict", () => {
+    const text = `${team}\nexport const crew = [factory];\n`;
+    expect(rewriteFountainFile("delivery/agents/team.ts", text)!.conflict).toMatch(/^factory is still used/);
+  });
+
+  test("a file with no retired kind plans nothing", () => {
+    const text = 'import { Agent } from "@intentius/chant-lexicon-fountain";\nexport const a = new Agent({\n  name: "a",\n});\n';
+    expect(rewriteFountainFile("agents.ts", text)).toBeNull();
+  });
+});

package/src/workspace/chant-migrations/fountain-retired-kinds.ts

@@ -0,0 +1,190 @@
+/**
+ * `fountain-retired-kinds` (#3987, managoat/managoat#2793): take a project's
+ * fountain declarations off the kinds Managoat v0.29.0 removed.
+ *
+ * Managoat dropped the team, its schedules, webhooks and persistent
+ * sandboxes. Since #3987 the fountain lexicon keeps `Teammate`, `Schedule`
+ * and `Webhook` only as stubs, and FTN025 fails a build that declares one, or
+ * an Agent with `sandbox_mode: "persistent"`. chud's template (and the studio
+ * kit's copy of it) declares a Teammate and a Schedule for its night shift
+ * and its factory, and gives the dispatcher a persistent sandbox, so a repo
+ * migrated off chud stopped building with chant 0.124.32.
+ *
+ * In each `chant` member, every `.ts` file that imports the fountain lexicon
+ * loses its `new Teammate(...)`, `new Schedule(...)` and `new Webhook(...)`
+ * declarations, those names from the import, any one-line constant only they
+ * used, and `sandbox_mode: "persistent"`. Each removed Schedule is listed as
+ * not moved: its clock now lives outside Managoat. A removed declaration whose
+ * name the file still uses elsewhere is a conflict, as is a file that still
+ * names a retired kind after the edits.
+ *
+ * The plan is empty once no fountain file declares a retired kind.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, NotMoved, PlanConflict, PlannedChange } from "../chant-migrations";
+import { applyEdits, readText, type Edit } from "./chud-lexicon-exit";
+
+export const FOUNTAIN_RETIRED_KINDS = "fountain-retired-kinds";
+
+const DESCRIPTION = "drop the fountain kinds Managoat removed: Teammate, Schedule, Webhook and persistent sandboxes (#3987)";
+
+const FOUNTAIN = "@intentius/chant-lexicon-fountain";
+const RETIRED = ["Teammate", "Schedule", "Webhook"] as const;
+
+const IMPORT = /import\s*\{([^}]*)\}\s*from\s*"@intentius\/chant-lexicon-fountain";/;
+/** A top-level declaration of a retired kind, with the doc comment just above it. */
+const DECLARATION = /(?:\/\*\*(?:(?!\*\/)[\s\S])*\*\/\n)?export const (\w+) = new (Teammate|Schedule|Webhook)\(\{\n[\s\S]*?\n\}\);\n(?:\n)?/g;
+const PERSISTENT = /^[ \t]*sandbox_mode:\s*"persistent",?[ \t]*\n/gm;
+
+/** The template's prose about what the edits remove. */
+const TEMPLATE_PROSE: Edit[] = [
+  {
+    find: " * build by this name (CHUD_FOUNTAIN_VAULT overrides it), and the two\n * Teammates below run with it.\n",
+    replace: " * build by this name (CHUD_FOUNTAIN_VAULT overrides it).\n",
+  },
+  {
+    find:
+      " * Steward does: a persistent sandbox (its checkout survives a turn) and no\n" +
+      " * permission prompts (nobody is at the keyboard; chant's own gates still need\n" +
+      " * a person). Its Teammate gives it one thread, so two schedule fires never\n" +
+      " * run two dispatchers on one checkout, and the Schedule is what triggers it.\n",
+    replace:
+      " * Steward does, with no permission prompts (nobody is at the keyboard;\n" +
+      " * chant's own gates still need a person). Managoat has no team or scheduler\n" +
+      " * any more: a clock outside it runs `chant run dispatch --on fountain`.\n",
+  },
+];
+
+/** The README row `chud-lexicon-exit` wrote, which names the factory's Schedule. */
+const README_EDITS: Edit[] = [
+  { find: " (the agents that build the app, as fountain specs; its factory Schedule still calls the kit's dispatch Op)", replace: " (the agents that build the app, as fountain specs)" },
+];
+
+function tsFiles(dir: string, rel = "", out: string[] = []): string[] {
+  let entries;
+  try {
+    entries = readdirSync(join(dir, rel), { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    const path = rel ? posix.join(rel, e.name) : e.name;
+    if (e.isDirectory()) {
+      if (e.name === "node_modules" || e.name === "dist" || e.name.startsWith(".")) continue;
+      tsFiles(dir, path, out);
+    } else if (e.name.endsWith(".ts") && !e.name.endsWith(".d.ts")) {
+      out.push(path);
+    }
+  }
+  return out;
+}
+
+/** The text with its comments and string contents blanked, so prose naming a kind is not a use of it. */
+const code = (text: string) => text.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*|"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*'|`(?:\\.|[^`\\])*`/g, '""');
+const uses = (text: string, name: string) => new RegExp(`(?<![\\w$.])${name}(?![\\w$])`).test(code(text));
+
+interface Rewrite {
+  text: string;
+  notMoved: NotMoved[];
+  conflict?: string;
+}
+
+/** The file without its retired declarations, or null when it has none. */
+export function rewriteFountainFile(path: string, original: string): Rewrite | null {
+  const imported = original.match(IMPORT);
+  if (!imported) return null;
+  const declared = [...original.matchAll(DECLARATION)];
+  const persistent = PERSISTENT.test(original);
+  PERSISTENT.lastIndex = 0;
+  if (declared.length === 0 && !persistent) return null;
+
+  const notMoved: NotMoved[] = [];
+  let text = original;
+  const removed: string[] = [];
+  const referenced = new Set<string>();
+  for (const [block, name, kind] of declared) {
+    text = text.replace(block, "");
+    removed.push(name!);
+    const body = block.slice(block.indexOf("new "));
+    for (const id of body.match(/\b[a-zA-Z_$][\w$]*\b/g) ?? []) referenced.add(id);
+    if (kind === "Schedule") {
+      const cron = body.match(/cron:\s*"([^"]+)"/)?.[1];
+      notMoved.push({
+        what: `the Schedule ${name}${cron ? ` (cron "${cron}")` : ""} in ${path}`,
+        where: "a clock outside Managoat, which has no scheduler: a CI schedule or a CronJob running `chant run <op> --on fountain`, or `chant operator --steward`",
+      });
+    } else if (kind === "Webhook") {
+      notMoved.push({ what: `the Webhook ${name} in ${path}`, where: "nothing: read a run's outcome from `chant run status` or `log`, or the conversation's event stream" });
+    }
+  }
+  text = text.replace(PERSISTENT, "");
+
+  // A one-line constant only the removed declarations used (the template's `nightlyMeta`).
+  for (const id of referenced) {
+    const line = new RegExp(`^export const ${id} = [^\\n]*;\\n\\n?`, "m");
+    const hit = text.match(line);
+    if (hit && !uses(text.replace(hit[0], ""), id)) text = text.replace(hit[0], "");
+  }
+
+  const names = imported[1]!.split(",").map((n) => n.trim()).filter(Boolean);
+  const kept = names.filter((n) => !(RETIRED as readonly string[]).includes(n) || uses(text.replace(IMPORT, ""), n));
+  if (kept.length !== names.length) text = text.replace(IMPORT, `import { ${kept.join(", ")} } from "${FOUNTAIN}";`);
+  text = applyEdits(text, TEMPLATE_PROSE).text.replace(/\n{3,}/g, "\n\n").replace(/\n+$/, "\n");
+
+  const dangling = removed.filter((n) => uses(text, n));
+  if (dangling.length > 0) return { text, notMoved, conflict: `${dangling.join(", ")} ${dangling.length === 1 ? "is" : "are"} still used after the retired declarations go. Remove ${dangling.length === 1 ? "that use" : "those uses"} by hand, then run the upgrade again` };
+  const still = RETIRED.filter((k) => new RegExp(`\\bnew ${k}\\(`).test(text));
+  if (still.length > 0) return { text, notMoved, conflict: `a ${still.join(", ")} declaration this migration cannot read. Remove it by hand, then run the upgrade again` };
+  return { text, notMoved };
+}
+
+interface Declaration {
+  members?: Array<{ dir?: string; kind?: string }>;
+}
+
+function planRetiredKinds(ctx: ChantMigrationContext): ChantMigrationPlan | null {
+  const { dir } = ctx;
+  let decl: Declaration | null = null;
+  try {
+    decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "null") as Declaration | null;
+  } catch {
+    decl = null;
+  }
+  const members = (decl?.members ?? []).filter((m) => m.kind === "chant" && m.dir).map((m) => posix.normalize(m.dir!));
+  if (members.length === 0 && existsSync(join(dir, "chant.config.ts"))) members.push(".");
+
+  const changes: PlannedChange[] = [];
+  const notMoved: NotMoved[] = [];
+  const conflicts: PlanConflict[] = [];
+  for (const member of members) {
+    for (const rel of tsFiles(join(dir, member))) {
+      const path = posix.join(member, rel);
+      const text = readText(dir, path);
+      if (text === undefined || !text.includes(FOUNTAIN)) continue;
+      const rewrite = rewriteFountainFile(path, text);
+      if (!rewrite) continue;
+      if (rewrite.conflict) {
+        conflicts.push({ path, reason: rewrite.conflict });
+        continue;
+      }
+      changes.push({ path, action: "write", why: "no Teammate, Schedule, Webhook or persistent sandbox, which Managoat removed and FTN025 fails", data: Buffer.from(rewrite.text) });
+      notMoved.push(...rewrite.notMoved);
+    }
+  }
+  if (changes.length === 0 && conflicts.length === 0) return null;
+
+  const readme = readText(dir, "README.md");
+  if (readme !== undefined && conflicts.length === 0) {
+    const edited = applyEdits(readme, README_EDITS).text;
+    if (edited !== readme) changes.push({ path: "README.md", action: "write", why: "the agents no longer declare a factory Schedule", data: Buffer.from(edited) });
+  }
+  return { id: FOUNTAIN_RETIRED_KINDS, description: DESCRIPTION, changes, notMoved, conflicts };
+}
+
+export const fountainRetiredKinds: ChantMigration = {
+  id: FOUNTAIN_RETIRED_KINDS,
+  description: DESCRIPTION,
+  plan: planRetiredKinds,
+};

package/src/workspace/chant-migrations.e2e.test.ts

@@ -34,6 +34,7 @@ import { CHUD_LEXICON_EXIT_ROLLBACK } from "./chant-migrations/chud-lexicon-exit
 import { CHUD_LEXICON_EXIT_SHIP_POLICY } from "./chant-migrations/chud-lexicon-exit-ship-policy";
 import { CHUD_LEXICON_EXIT_FLY_SITE, chudLexiconExitFlySite } from "./chant-migrations/chud-lexicon-exit-fly-site";
 import { CHUD_LEXICON_EXIT_LIVE_NAMES } from "./chant-migrations/chud-lexicon-exit-live-names";
+import { FOUNTAIN_RETIRED_KINDS } from "./chant-migrations/fountain-retired-kinds";
 import { readerVersion } from "./declaration";
 import { runChecks } from "./lineage-check";
 import { initFromCommand } from "./lineage-init";
@@ -174,6 +175,10 @@ describe.each(["dir", "git"] as const)("chud-lexicon-exit, from a %s source", (f
     expect(out).toContain(`chant migration: ${CHUD_LEXICON_EXIT_ROLLBACK} (applied)`);
     expect(out).toContain("write: delivery/ops/rollback.op.ts");
     expect(out).not.toContain("not moved: the release's steps after the ship gate");
+    // #3987: the template's Teammates, Schedules and persistent sandbox fail FTN025, so a migrated repo would not build.
+    expect(out).toContain(`chant migration: ${FOUNTAIN_RETIRED_KINDS} (applied)`);
+    expect(out).toContain("write: delivery/agents/team.ts");
+    expect(out).toMatch(/not moved: the Schedule factoryDispatch \(cron "\*\/15 \* \* \* \*"\) in delivery\/agents\/team\.ts -> a clock outside Managoat/);
     // #2805: the plan lists README.md, CLAUDE.md and design/CLAUDE.md as
     // changed, not silently left describing what the migration just deleted.
     expect(out).toContain("write: README.md");

package/src/workspace/chant-migrations.ts

@@ -42,6 +42,7 @@ import { chudLexiconExitShipInputs } from "./chant-migrations/chud-lexicon-exit-
 import { chudLexiconExitShipPolicy } from "./chant-migrations/chud-lexicon-exit-ship-policy";
 import { chudLexiconExitFlySite } from "./chant-migrations/chud-lexicon-exit-fly-site";
 import { chudLexiconExitLiveNames } from "./chant-migrations/chud-lexicon-exit-live-names";
+import { fountainRetiredKinds } from "./chant-migrations/fountain-retired-kinds";
 
 /** One file a plan writes or deletes, relative to the scope. */
 export interface PlannedChange {
@@ -98,6 +99,7 @@ export const CHANT_MIGRATIONS: readonly ChantMigration[] = [
   chudLexiconExitShipPolicy,
   chudLexiconExitFlySite,
   chudLexiconExitLiveNames,
+  fountainRetiredKinds,
 ];
 
 /** The plans for a scope: each migration not yet in the lineage that finds something to move. */

package/src/workspace/checks/boxes.ts

@@ -28,15 +28,15 @@
  * listed here after these two.
  *
  * WSP125 (`box-fountain-callback-undeclared`, #2780) is the one credential a
- * box gets without asking. fountain v0.21.0 gives every persistent sandbox a
- * callback token scoped to its owner (`FOUNTAIN_TOKEN`, `sandbox_api_access:
- * owner`), and a fountain `Box` is always persistent, so its member's block
- * has to say so: the capability `fountain-callback`, brokered by `fountain`,
+ * box gets without asking. fountain gives every sandbox a callback token
+ * scoped to its owner (`FOUNTAIN_TOKEN`, `sandbox_api_access: owner`) unless
+ * its conversation asks for none, and a fountain `Box` runs with it, so its
+ * member's block has to say so: the capability `fountain-callback`, brokered by `fountain`,
  * with scope `owner`. It is named apart from `fountain`, the API access a
  * lobby may broker for the same box. A member builds a Box when one of its TypeScript or JavaScript files
  * imports `Box` from `@intentius/chant-lexicon-fountain` and calls it, read as
- * syntax and never run. Upstream, managoat/fountain#2497 asks for a way to run
- * a persistent agent with no callback token.
+ * syntax and never run. Upstream, managoat/fountain#2497 asked for a way to run
+ * a box's agent with no callback token.
  *
  * WSP126 (`box-intent-unknown`) and WSP127 (`box-intent-unconstrained`), #2850,
  * read the decision record a box block names as its intent (`box-intent.ts`).
@@ -75,7 +75,7 @@ export const WSP_BOX_FOUNTAIN_CALLBACK = "WSP125";
 export const WSP_BOX_INTENT_UNKNOWN = "WSP126";
 export const WSP_BOX_INTENT_UNCONSTRAINED = "WSP127";
 
-/** The fountain lexicon's package, whose `Box` composite runs a persistent sandbox. */
+/** The fountain lexicon's package, whose `Box` composite declares a box's agent. */
 const FOUNTAIN_LEXICON = "@intentius/chant-lexicon-fountain";
 
 /**
@@ -402,7 +402,7 @@ export const BOX_CHECKS: readonly WorkspaceCheck[] = [
     id: WSP_BOX_FOUNTAIN_CALLBACK,
     name: "box-fountain-callback-undeclared",
     description:
-      "A box member that builds a fountain Box declares the callback token fountain gives its persistent sandbox: the fountain-callback capability, brokered by fountain, with scope owner.",
+      "A box member that builds a fountain Box declares the callback token fountain gives its sandbox: the fountain-callback capability, brokered by fountain, with scope owner.",
     severity: "error",
     configurable: true,
     check(ctx) {
@@ -442,7 +442,7 @@ export const BOX_CHECKS: readonly WorkspaceCheck[] = [
           severity: this.severity,
           code: "box-fountain-callback-undeclared",
           message:
-            `box-fountain-callback-undeclared: member ${m.name} builds a fountain Box (${at.path}), and fountain v0.21.0 gives a persistent box's sandbox ` +
+            `box-fountain-callback-undeclared: member ${m.name} builds a fountain Box (${at.path}), and fountain gives a box's sandbox ` +
             `a callback token scoped to its owner (FOUNTAIN_TOKEN); ${why}. Declare ${expected} in the box block ` +
             `(managoat/fountain#2497 tracks running without it)`,
           entity: m.name,