@cohortapp/agent-sdk 2.11.15 → 2.13.0

package/lib/design/write.mjs

@@ -0,0 +1,275 @@
+/**
+ * lib/design/write.mjs — the effect edge of the design sync (WP-M7 mechanic 4).
+ *
+ * `design-md.mjs` decides WHAT the files say and `refresh-gate.mjs` decides
+ * WHEN; this module is the only place that touches the disk, so the CLI
+ * (`maestro design sync`) and the daemon's poller write the same bytes with the
+ * same modes and the same idempotence rule.
+ *
+ * IDEMPOTENCE IS BY BYTES, not by timestamp. A re-sync of an unchanged
+ * foundation must not touch DESIGN.md — the file is read by editors and skills,
+ * and a pointless mtime bump is how a watcher storms and how a git tree looks
+ * dirty for no reason. So each file is read back and compared before writing.
+ * That also means `generatedAt` must NOT be part of the rendered bytes when
+ * idempotence matters: the caller passes the SAME `generatedAt` it recorded on
+ * the previous sync, or none. (`sync.mjs` callers pass the stored value.)
+ *
+ * EVERY write here goes through `lib/fs-atomic.mjs` — the JSON snapshot and
+ * both markdown files. There are TWO writers of the same two absolute paths (a
+ * hand-run `maestro design sync` and the daemon's 15-minute poll), and a design
+ * skill reads `$AGENT_ROOT/DESIGN.md` at arbitrary moments; an in-place
+ * `writeFileSync` would let it read a half-written frontmatter block. The mode
+ * is applied with an explicit `chmod` after the rename as well as on the temp
+ * file, because Node honours a `mode` option only when it CREATES a file — a
+ * DESIGN.md some other tool left at 0600 would otherwise stay 0600 forever.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/design/write
+ */
+
+"use strict";
+
+import { chmodSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { writeFileAtomic, writeJsonAtomic } from "../fs-atomic.mjs";
+import { renderDesignBundle } from "./design-md.mjs";
+import { DESIGN_STATE_REL, foundationVersion, foundationVersionLabel } from "./refresh-gate.mjs";
+
+/** The mode the generated docs are written with (readable by any tool on the seat). */
+export const DESIGN_FILE_MODE = 0o644;
+
+/**
+ * The workspace/brand name for the rendered heading, from the loaded org config.
+ *
+ * SHARED ON PURPOSE. `maestro design sync` and the daemon's poller both write
+ * DESIGN.md, and the heading is part of the rendered bytes — two definitions of
+ * "what is this workspace called" would make a hand-run sync and an automatic
+ * one disagree, and the idempotence rule above would then rewrite the file on
+ * every alternation. One function, both callers.
+ *
+ * The foundation's own `positioning` is prose, not a name, so it is never used
+ * here. Nothing is invented: an org config without a name reads "Workspace".
+ *
+ * @param {object} cfg the loaded org config (`lib/org/client.mjs#loadOrgConfig`)
+ * @returns {string}
+ */
+export function workspaceName(cfg) {
+  const org = cfg && typeof cfg === "object" ? cfg.org : null;
+  const cohort = org && typeof org === "object" ? org.cohort : null;
+  const name = cohort && typeof cohort === "object" ? cohort.orgName || cohort.workspace : null;
+  return typeof name === "string" && name.trim() ? name.trim() : "Workspace";
+}
+
+/**
+ * Write the rendered bundle, skipping any file whose bytes are already correct.
+ *
+ * @param {object} o
+ * @param {Array<{rel:string, content:string}>} o.files rendered by `renderDesignBundle`
+ * @param {string} o.outDir  where the two markdown files go
+ * @param {object} [io] injectable I/O for tests: {readFileImpl, writeFileImpl, existsImpl, mkdirImpl}
+ * @returns {{written:string[], unchanged:string[]}}
+ */
+export function writeDesignFiles({ files, outDir }, io = {}) {
+  const readImpl = io.readFileImpl || ((p) => readFileSync(p, "utf8"));
+  const writeImpl = io.writeFileImpl || ((p, data, mode) => {
+    writeFileAtomic(p, data, { mode });
+    // The rename published a file created with `mode`, but only because it was
+    // new. chmod the published name too, so a pre-existing file that some other
+    // tool left at a tighter mode is corrected rather than inherited.
+    try { chmodSync(p, mode); } catch { /* best effort: the bytes matter more than the bits */ }
+  });
+  const existsImpl = io.existsImpl || existsSync;
+  const mkdirImpl = io.mkdirImpl || ((p) => mkdirSync(p, { recursive: true }));
+  const written = [];
+  const unchanged = [];
+  if (!existsImpl(outDir)) mkdirImpl(outDir);
+  for (const file of Array.isArray(files) ? files : []) {
+    if (!file || typeof file.rel !== "string" || typeof file.content !== "string") continue;
+    const target = join(outDir, file.rel);
+    let current = null;
+    try {
+      current = existsImpl(target) ? readImpl(target) : null;
+    } catch {
+      current = null; // unreadable is the same as absent: rewrite it
+    }
+    if (current === file.content) {
+      unchanged.push(file.rel);
+      continue;
+    }
+    writeImpl(target, file.content, DESIGN_FILE_MODE);
+    written.push(file.rel);
+  }
+  return { written, unchanged };
+}
+
+/**
+ * Persist the foundation snapshot the gate reads back next tick.
+ * `{fetchedAt, version, versionLabel, foundation}` — durable JSON, atomic.
+ *
+ * @param {string} agentRoot
+ * @param {{fetchedAt:string, version:string|null, versionLabel?:string, foundation:object}} doc
+ * @param {object} [io] {writeJsonImpl, mkdirImpl}
+ * @returns {string} the path written
+ */
+export function writeFoundationState(agentRoot, doc, io = {}) {
+  const path = join(String(agentRoot || ""), DESIGN_STATE_REL);
+  const mkdirImpl = io.mkdirImpl || ((p) => mkdirSync(p, { recursive: true }));
+  mkdirImpl(dirname(path));
+  (io.writeJsonImpl || writeJsonAtomic)(path, doc);
+  return path;
+}
+
+/**
+ * Read back the last synced snapshot. Returns null when absent or corrupt — a
+ * corrupt snapshot is treated as "never synced", which re-syncs rather than
+ * wedging.
+ * @param {string} agentRoot
+ * @param {object} [io] {readFileImpl}
+ * @returns {{fetchedAt?:string, version?:string|null, versionLabel?:string, foundation?:object}|null}
+ */
+export function readFoundationState(agentRoot, io = {}) {
+  const path = join(String(agentRoot || ""), DESIGN_STATE_REL);
+  try {
+    const raw = (io.readFileImpl || ((p) => readFileSync(p, "utf8")))(path);
+    const doc = JSON.parse(raw);
+    return doc && typeof doc === "object" && !Array.isArray(doc) ? doc : null;
+  } catch {
+    return null; // absent or corrupt → re-sync
+  }
+}
+
+/**
+ * The per-output-directory render stamps from a state snapshot, as a mutable
+ * map of resolved path → ISO string.
+ *
+ * MIGRATION. Snapshots written before the map existed carry one bare
+ * `renderedAt` string, which described the agent dir (the only directory the
+ * daemon ever writes). Reading it as that entry means an upgraded seat finds
+ * its DESIGN.md already matching and rewrites nothing.
+ *
+ * @param {object|null} prior
+ * @param {string} agentRoot
+ * @returns {Record<string,string>}
+ */
+export function priorRenderStamps(prior, agentRoot) {
+  const out = {};
+  const p = prior && typeof prior === "object" ? prior : {};
+  if (p.rendered && typeof p.rendered === "object" && !Array.isArray(p.rendered)) {
+    for (const [k, v] of Object.entries(p.rendered)) {
+      if (typeof k === "string" && typeof v === "string" && v) out[k] = v;
+    }
+  }
+  const legacy = typeof p.renderedAt === "string" && p.renderedAt ? p.renderedAt : "";
+  const rootKey = resolve(String(agentRoot || ""));
+  if (legacy && !out[rootKey]) out[rootKey] = legacy;
+  return out;
+}
+
+/**
+ * Do all rendered files already match what is on disk? The idempotence probe.
+ * @param {Array<{rel:string, content:string}>} files
+ * @param {string} outDir
+ * @param {object} [io]
+ * @returns {boolean}
+ */
+export function filesMatch(files, outDir, io = {}) {
+  const readImpl = io.readFileImpl || ((p) => readFileSync(p, "utf8"));
+  const existsImpl = io.existsImpl || existsSync;
+  for (const file of Array.isArray(files) ? files : []) {
+    const target = join(outDir, file.rel);
+    let current = null;
+    try {
+      current = existsImpl(target) ? readImpl(target) : null;
+    } catch {
+      return false; // unreadable → rewrite
+    }
+    if (current !== file.content) return false;
+  }
+  return true;
+}
+
+/**
+ * Render a fetched foundation and land it on the seat: DESIGN.md + PRODUCT.md in
+ * `outDir`, the snapshot in `state/design/foundation.json`. The ONE code path
+ * both `maestro design sync` and the daemon's poller use, so a hand-run sync and
+ * an automatic one produce identical bytes.
+ *
+ * THE `generatedAt` DANCE. A timestamp inside the rendered bytes would make
+ * every sync a rewrite, defeating the idempotence the whole design turns on. So
+ * the files are first rendered carrying the PREVIOUS sync's stamp: if they then
+ * match the disk byte-for-byte, nothing changed and nothing is written. Only
+ * when something genuinely differs are they re-rendered with `now` — so the
+ * stamp means "when this content was minted", which is the honest reading, and
+ * an unchanged foundation touches no file.
+ *
+ * THE STAMP IS PER OUTPUT DIRECTORY (`rendered`, keyed by resolved path). One
+ * shared stamp is a permanent rewrite loop the moment a second directory
+ * exists: `maestro design sync --out docs/brand` stamps the state with its own
+ * `now`, the daemon's next poll of the agent dir renders with that stamp, does
+ * not match ITS files, rewrites them and re-stamps — and each lane then
+ * invalidates the other's files forever, with a foundation that never changed.
+ * A legacy state file carrying a bare `renderedAt` string is read as the agent
+ * dir's entry, so an existing seat migrates without one spurious rewrite.
+ *
+ * @param {object} o
+ * @param {string} o.agentRoot          the agent dir (where state/ lives)
+ * @param {string} [o.outDir]           where the docs go (default: agentRoot)
+ * @param {object} o.result             the `branding.getFoundation` result frame's `result`
+ * @param {number} o.now                epoch ms (injected)
+ * @param {string} [o.name]             workspace/brand name for the heading
+ * @param {string} [o.source]           provenance line
+ * @param {object} [io]                 injectable I/O (see writeDesignFiles / writeFoundationState)
+ * @returns {{written:string[], unchanged:string[], version:string|null, statePath:string, outDir:string}}
+ */
+export function syncDesign(o, io = {}) {
+  const agentRoot = String(o.agentRoot || "");
+  const outDir = String(o.outDir || agentRoot);
+  const now = Number.isFinite(o.now) ? o.now : 0;
+  const nowIso = new Date(now).toISOString();
+  const result = o.result && typeof o.result === "object" ? o.result : {};
+  const foundation = result.foundation && typeof result.foundation === "object" ? result.foundation : {};
+  const version = foundationVersion(result);
+  const versionLabel = foundationVersionLabel(result);
+  const prior = readFoundationState(agentRoot, io);
+  const rendered = priorRenderStamps(prior, agentRoot);
+  const key = resolve(outDir);
+  const priorStamp = rendered[key] || nowIso;
+
+  const base = { name: o.name, source: o.source, versionId: version || "", versionLabel };
+  let renderedAt = priorStamp;
+  let files = renderDesignBundle(foundation, { ...base, generatedAt: renderedAt });
+  let out = { written: [], unchanged: files.map((f) => f.rel) };
+  if (!filesMatch(files, outDir, io)) {
+    renderedAt = nowIso;
+    files = renderDesignBundle(foundation, { ...base, generatedAt: renderedAt });
+    out = writeDesignFiles({ files, outDir }, io);
+  }
+  rendered[key] = renderedAt;
+  const statePath = writeFoundationState(
+    agentRoot,
+    {
+      fetchedAt: nowIso,
+      // The agent dir's own stamp stays at the top level: it is what a reader
+      // (and an older SDK) means by "when was DESIGN.md minted".
+      renderedAt: rendered[resolve(agentRoot)] || renderedAt,
+      rendered,
+      version: version || null,
+      versionLabel,
+      foundation,
+    },
+    io,
+  );
+  return { ...out, version: version || null, statePath, outDir };
+}
+
+export default {
+  workspaceName,
+  priorRenderStamps,
+  writeDesignFiles,
+  writeFoundationState,
+  readFoundationState,
+  filesMatch,
+  syncDesign,
+  DESIGN_FILE_MODE,
+};

package/lib/design/write.test.mjs

@@ -0,0 +1,241 @@
+/**
+ * write.test.mjs — the effect edge of the design sync (WP-M7 mechanic 4).
+ *
+ * Real files in a temp dir, not stubs: the claims worth holding here are about
+ * the FILESYSTEM — that an unchanged foundation touches no mtime, and that the
+ * two markdown files land at 0644 so any tool on the seat can read them.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { chmodSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, writeFileSync, statSync, utimesSync, existsSync, rmSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { tmpdir } from "node:os";
+
+import { syncDesign, writeDesignFiles, writeFoundationState, readFoundationState, filesMatch, workspaceName, DESIGN_FILE_MODE } from "./write.mjs";
+import { renderDesignBundle } from "./design-md.mjs";
+import { DESIGN_STATE_REL } from "./refresh-gate.mjs";
+
+const NOW = Date.parse("2026-09-08T12:00:00Z");
+const FIXTURE = JSON.parse(readFileSync(new URL("./fixtures/foundation.json", import.meta.url), "utf8"));
+
+/** A `branding.getFoundation` result frame's `result`. */
+const result = (over = {}) => ({
+  foundation: FIXTURE,
+  version: { id: "bv_01HQZ", seq: 7, label: "V2.7" },
+  headVersionId: "bv_01HQZ",
+  isHead: true,
+  unversioned: false,
+  history: [],
+  ...over,
+});
+
+function tmpRoot(t) {
+  const dir = mkdtempSync(join(tmpdir(), "maestro-design-write-"));
+  t.after(() => rmSync(dir, { recursive: true, force: true }));
+  return dir;
+}
+
+test("a first sync writes both files plus the state snapshot", (t) => {
+  const root = tmpRoot(t);
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  assert.deepEqual(out.written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.deepEqual(out.unchanged, []);
+  assert.equal(out.version, "bv_01HQZ");
+  assert.equal(out.outDir, root);
+
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /^---\nname: "Northwind"\n/);
+  assert.match(design, /\{colors\.primary\}/);
+  assert.match(readFileSync(join(root, "PRODUCT.md"), "utf8"), /# Northwind — product voice/);
+
+  const state = JSON.parse(readFileSync(join(root, DESIGN_STATE_REL), "utf8"));
+  assert.equal(state.version, "bv_01HQZ");
+  assert.equal(state.versionLabel, "V2.7");
+  assert.equal(state.fetchedAt, "2026-09-08T12:00:00.000Z");
+  assert.deepEqual(state.foundation, FIXTURE, "the raw foundation is kept verbatim for the next gate read");
+});
+
+test("both markdown files are 0644", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) {
+    assert.equal(statSync(join(root, rel)).mode & 0o777, DESIGN_FILE_MODE, rel);
+  }
+});
+
+test("re-syncing an unchanged foundation rewrites NOTHING — mtimes are untouched", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  // Backdate both files so any rewrite is unmistakable.
+  const old = new Date(NOW - 86_400_000);
+  for (const rel of ["DESIGN.md", "PRODUCT.md"]) utimesSync(join(root, rel), old, old);
+  const before = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(root, rel)).mtimeMs);
+
+  // A LATER clock, deliberately: the timestamp inside the file must not be what
+  // makes a sync a rewrite, or the interval poll would churn the tree forever.
+  const again = syncDesign({ agentRoot: root, result: result(), now: NOW + 20 * 60_000, name: "Northwind" });
+  assert.deepEqual(again.written, [], "nothing written");
+  assert.deepEqual(again.unchanged, ["DESIGN.md", "PRODUCT.md"]);
+
+  const after = ["DESIGN.md", "PRODUCT.md"].map((rel) => statSync(join(root, rel)).mtimeMs);
+  assert.deepEqual(after, before, "the files were not touched at all");
+
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /\*\*Synced:\*\* 2026-09-08T12:00:00\.000Z/, "the stamp still says when the CONTENT was minted");
+
+  // The snapshot is still refreshed, so the gate knows the seat did check.
+  const state = JSON.parse(readFileSync(join(root, DESIGN_STATE_REL), "utf8"));
+  assert.equal(state.fetchedAt, "2026-09-08T12:20:00.000Z");
+  assert.equal(state.renderedAt, "2026-09-08T12:00:00.000Z");
+});
+
+test("a changed foundation rewrites the affected file and re-stamps it", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+
+  const moved = JSON.parse(JSON.stringify(FIXTURE));
+  moved.colors[2].value = "#111111";
+  const out = syncDesign({
+    agentRoot: root,
+    result: result({ foundation: moved, headVersionId: "bv_02", version: { id: "bv_02", seq: 8, label: "V2.8" } }),
+    now: NOW + 20 * 60_000,
+    name: "Northwind",
+  });
+
+  assert.ok(out.written.includes("DESIGN.md"));
+  assert.equal(out.version, "bv_02");
+  const design = readFileSync(join(root, "DESIGN.md"), "utf8");
+  assert.match(design, /primary-moss: "#111111"/);
+  assert.match(design, /\*\*Synced:\*\* 2026-09-08T12:20:00\.000Z/);
+  assert.match(design, /\*\*Version:\*\* V2\.8/);
+});
+
+test("--out sends the docs elsewhere; the snapshot always stays under the agent root", (t) => {
+  const root = tmpRoot(t);
+  const outDir = join(root, "docs", "brand");
+  const out = syncDesign({ agentRoot: root, outDir, result: result(), now: NOW, name: "Northwind" });
+
+  assert.equal(out.outDir, outDir);
+  assert.ok(existsSync(join(outDir, "DESIGN.md")));
+  assert.ok(!existsSync(join(root, "DESIGN.md")));
+  assert.ok(existsSync(join(root, DESIGN_STATE_REL)));
+});
+
+test("writeDesignFiles skips a file whose bytes already match and rewrites an unreadable one", (t) => {
+  const root = tmpRoot(t);
+  const files = renderDesignBundle(FIXTURE, { name: "Northwind" });
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }).written, ["DESIGN.md", "PRODUCT.md"]);
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }), { written: [], unchanged: ["DESIGN.md", "PRODUCT.md"] });
+
+  writeFileSync(join(root, "DESIGN.md"), "someone edited this by hand\n");
+  assert.deepEqual(writeDesignFiles({ files, outDir: root }).written, ["DESIGN.md"], "a hand edit is overwritten — the file is generated");
+
+  const boom = writeDesignFiles({ files, outDir: root }, { readFileImpl: () => { throw new Error("EIO"); } });
+  assert.deepEqual(boom.written, ["DESIGN.md", "PRODUCT.md"], "unreadable is treated as absent");
+});
+
+test("writeDesignFiles ignores malformed entries rather than throwing", (t) => {
+  const root = tmpRoot(t);
+  const out = writeDesignFiles({ files: [null, { rel: "A.md" }, { content: "x" }, { rel: "ok.md", content: "y" }], outDir: root });
+  assert.deepEqual(out.written, ["ok.md"]);
+  assert.deepEqual(writeDesignFiles({ files: "not a list", outDir: root }), { written: [], unchanged: [] });
+});
+
+test("readFoundationState reads back what writeFoundationState wrote; corrupt reads as never-synced", (t) => {
+  const root = tmpRoot(t);
+  assert.equal(readFoundationState(root), null, "absent → null");
+
+  const path = writeFoundationState(root, { fetchedAt: "2026-09-08T12:00:00.000Z", version: "bv_1", foundation: { colors: [] } });
+  assert.equal(path, join(root, DESIGN_STATE_REL));
+  assert.equal(readFoundationState(root).version, "bv_1");
+
+  writeFileSync(path, "{ not json");
+  assert.equal(readFoundationState(root), null, "corrupt → null → re-sync, never a wedge");
+
+  writeFileSync(path, JSON.stringify([1, 2]));
+  assert.equal(readFoundationState(root), null, "an array is not a snapshot");
+});
+
+test("filesMatch is the idempotence probe the CLI's claim rests on", (t) => {
+  const root = tmpRoot(t);
+  const files = renderDesignBundle(FIXTURE, { name: "Northwind" });
+  assert.equal(filesMatch(files, root), false, "nothing on disk yet");
+  writeDesignFiles({ files, outDir: root });
+  assert.equal(filesMatch(files, root), true);
+  writeFileSync(join(root, "PRODUCT.md"), "drift\n");
+  assert.equal(filesMatch(files, root), false);
+});
+
+test("workspaceName reads the org config and invents nothing", () => {
+  assert.equal(workspaceName({ org: { cohort: { orgName: "Northwind" } } }), "Northwind");
+  assert.equal(workspaceName({ org: { cohort: { workspace: "adaptic-hq" } } }), "adaptic-hq");
+  assert.equal(workspaceName({ org: { cohort: { orgName: "  " } } }), "Workspace");
+  assert.equal(workspaceName({}), "Workspace");
+  assert.equal(workspaceName(null), "Workspace");
+});
+
+test("a state directory that does not exist yet is created", (t) => {
+  const root = join(tmpRoot(t), "not", "made", "yet");
+  mkdirSync(root, { recursive: true });
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  assert.ok(existsSync(out.statePath));
+});
+
+// ── two output directories, one state file ──────────────────────────────────
+
+test("the daemon's agent dir and a --out directory do not invalidate each other, ever", (t) => {
+  // The scenario: an operator runs `maestro design sync --out docs/brand`
+  // (advertised in the guide) on a seat whose daemon polls the agent dir every
+  // 15 minutes. With one shared render stamp, each lane re-stamped the state
+  // and the other lane then found its own files "stale" — both files rewritten
+  // on every tick, forever, with a foundation that never changed.
+  const root = tmpRoot(t);
+  const brand = join(root, "docs", "brand");
+  let now = NOW;
+  const daemon = () => syncDesign({ agentRoot: root, result: result(), now: (now += 900_000), name: "Northwind" });
+  const cli = () => syncDesign({ agentRoot: root, outDir: brand, result: result(), now: (now += 60_000), name: "Northwind" });
+
+  assert.deepEqual(daemon().written, ["DESIGN.md", "PRODUCT.md"], "first write of the agent dir");
+  assert.deepEqual(cli().written, ["DESIGN.md", "PRODUCT.md"], "first write of docs/brand");
+
+  for (let i = 0; i < 6; i++) {
+    assert.deepEqual(daemon().written, [], `daemon poll ${i + 1} rewrote nothing`);
+    assert.deepEqual(cli().written, [], `--out run ${i + 1} rewrote nothing`);
+  }
+
+  const state = readFoundationState(root);
+  assert.equal(typeof state.rendered, "object");
+  assert.equal(Object.keys(state.rendered).length, 2, "one stamp per output directory");
+  assert.equal(state.renderedAt, state.rendered[resolve(root)], "the top-level stamp still describes the agent dir");
+});
+
+test("a legacy state file with a bare renderedAt migrates without a spurious rewrite", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  // Rewrite the snapshot in the pre-map shape, as an older SDK left it.
+  const doc = readFoundationState(root);
+  const legacy = { ...doc };
+  delete legacy.rendered;
+  writeFoundationState(root, legacy);
+  assert.equal(readFoundationState(root).rendered, undefined);
+
+  const out = syncDesign({ agentRoot: root, result: result(), now: NOW + 3_600_000, name: "Northwind" });
+  assert.deepEqual(out.written, [], "the old stamp is read as the agent dir's, so the bytes still match");
+  assert.equal(readFoundationState(root).rendered[resolve(root)], legacy.renderedAt);
+});
+
+test("both markdown files are published atomically and forced to 0644 even over a tighter file", (t) => {
+  const root = tmpRoot(t);
+  syncDesign({ agentRoot: root, result: result(), now: NOW, name: "Northwind" });
+  // Some other tool tightens the mode and truncates the content.
+  chmodSync(join(root, "DESIGN.md"), 0o600);
+  writeFileSync(join(root, "DESIGN.md"), "half a file");
+  syncDesign({ agentRoot: root, result: result(), now: NOW + 1000, name: "Northwind" });
+  assert.equal(statSync(join(root, "DESIGN.md")).mode & 0o777, DESIGN_FILE_MODE, "chmod runs on a rewrite, not only on create");
+
+  // No temp file is left behind by the atomic publish.
+  assert.deepEqual(readdirSync(root).filter((f) => f.includes(".tmp.")), []);
+});

package/lib/feature-init.mjs

@@ -39,10 +39,10 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
-  writeFileSync,
 } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { spawnSync } from "node:child_process";
+import { writeJsonAtomic } from "./fs-atomic.mjs";
 
 export const FEATURE_REGISTRY_RELATIVE = "framework-features.json";
 export const AGENT_STATE_RELATIVE = ".maestro/features.json";
@@ -116,7 +116,7 @@ export function loadAgentState(agentRoot) {
 export function saveAgentState(agentRoot, state) {
   const statePath = getStatePath(agentRoot);
   mkdirSync(dirname(statePath), { recursive: true });
-  writeFileSync(statePath, JSON.stringify(state, null, 2) + "\n");
+  writeJsonAtomic(statePath, state);
 }
 
 // ---------------------------------------------------------------------------

package/lib/mcp/server.test.mjs

@@ -166,19 +166,24 @@ test("tools/list: full active surface (email tools present — family is vendore
   // other desk block, these eight are GENERATED from the vendored protocol
   // declaration (lib/org/resource-tools.mjs), so this transport gets them, and
   // every future resource method, without a second hand-written table.
-  assert.equal(tools.length, 141, "email + artifact + desk families vendored → 141 tools");
+  // 141 → 144: the front-door session (2026-09). board_mine / board_track /
+  // session_status — "my tasks across every board" was unreadable from any
+  // plane (board.ready is unassigned-only), the inbound→board seam had no
+  // accepted/done ends, and nothing could tell a session whether the main
+  // session was alive.
+  assert.equal(tools.length, 144, "email + artifact + desk + front-door families vendored → 144 tools");
   const names = tools.map((t) => t.name);
-  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "task_assign", "board_ready", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file", "resource_list", "resource_attach_file"]) {
+  for (const expected of ["org_whoami", "org_describe", "org_rpc", "org_read", "messaging_send", "task_assign", "board_ready", "board_mine", "board_track", "session_status", "email_send", "email_inbox", "artifact_create", "artifact_act", "artifact_catalog", "email_mailboxes", "email_draft_send", "files_list", "calendar_find_a_time", "crm_list_deals", "books_reports", "meetings_recap_file", "resource_list", "resource_attach_file"]) {
     assert.ok(names.includes(expected), `${expected} listed`);
   }
   assert.ok(tools.every((t) => t.inputSchema && t.inputSchema.type === "object"));
   h.server.stop();
 });
 
-test("tools/list honours the email gate (emailAvailable:false → 136 tools)", async () => {
+test("tools/list honours the email gate (emailAvailable:false → 139 tools)", async () => {
   const h = harness({ emailAvailable: false });
   const r = await h.request("tools/list", {});
-  assert.equal(r.result.tools.length, 136, "the 5 own-mailbox email tools drop out");
+  assert.equal(r.result.tools.length, 139, "the 5 own-mailbox email tools drop out");
   const names = new Set(r.result.tools.map((t) => t.name));
   // The five own-mailbox tools (email:true) are gated out …
   for (const gated of ["email_send", "email_inbox", "email_message", "email_thread", "email_mark_read"]) {

package/lib/model-router/spawn.test.mjs

@@ -423,3 +423,24 @@ test("DeepSeek session retarget env is built when DeepSeek is the cheap candidat
   // Foreign keys scrubbed.
   assert.equal(seenEnv.MOONSHOT_API_KEY, undefined);
 });
+
+test("buildChildEnv KEEPS CLAUDE_CODE_OAUTH_TOKEN — the subscription token is not a foreign credential (§3.1)", () => {
+  // The scrub regex ends in `_AUTH_TOKEN$`; `_OAUTH_TOKEN` must not match it,
+  // otherwise every daemon spawn on the oauth-token path would silently fall
+  // back to an expired keychain login. Pinned here so a "tidy" of the regex
+  // cannot re-open F1.
+  const base = {
+    PATH: "/usr/bin",
+    CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-example",
+    MAESTRO_PREFER_SUBSCRIPTION_AUTH: "1",
+    SOME_AUTH_TOKEN: "tok",
+  };
+  const stock = buildChildEnv(base, {});
+  assert.equal(stock.CLAUDE_CODE_OAUTH_TOKEN, "sk-ant-oat01-example");
+  assert.equal(stock.MAESTRO_PREFER_SUBSCRIPTION_AUTH, "1");
+  assert.equal(stock.SOME_AUTH_TOKEN, undefined, "a real *_AUTH_TOKEN is still scrubbed");
+  // A retarget (third-party session) keeps it too: the token is harmless to a
+  // foreign base URL and the ANTHROPIC_API_KEY="" discipline is what fences it.
+  const retarget = buildChildEnv(base, { ANTHROPIC_BASE_URL: "https://api.moonshot.ai/anthropic", ANTHROPIC_API_KEY: "" });
+  assert.equal(retarget.CLAUDE_CODE_OAUTH_TOKEN, "sk-ant-oat01-example");
+});