@animalabs/connectome-host 0.7.4 → 0.8.0

package/test/recipe-save-unresolved.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Tests for unresolved recipe persistence: the `.recipe.json` snapshot in
+ * $DATA_DIR must never contain substituted secrets.
+ *
+ * Motivating finding (external recipe review against a production VM):
+ * loadRecipe substituted every `${VAR}` — including access tokens — into the
+ * recipe, and resolveRecipe then serialised the RESOLVED recipe to
+ * $DATA_DIR/.recipe.json, a directory deployments bind-mount and back up.
+ *
+ * Contract under test:
+ *   - loadRecipeDetailed returns the resolved recipe for the runtime AND a
+ *     `persistable` pre-substitution form; saveRecipe writes the latter, so
+ *     the on-disk snapshot keeps `${VAR}` literals, never the secret values.
+ *   - loadSavedRecipe re-runs substitution against the CURRENT environment
+ *     (secret rotation takes effect on restart), hard-failing when a
+ *     required var has gone missing.
+ *   - Legacy snapshots (saved fully resolved by older versions, no marker)
+ *     still load verbatim — including ones with a literal `${...}` in prose.
+ *   - The snapshot file is chmod'd 0600 even when overwriting a legacy file.
+ *   - A URL systemPrompt is persisted as the URL and re-fetched on resume.
+ */
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, statSync, chmodSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import {
+  loadRecipe,
+  loadRecipeDetailed,
+  saveRecipe,
+  loadSavedRecipe,
+  SAVED_RECIPE_UNRESOLVED_KEY,
+} from '../src/recipe.js';
+
+const SECRET = 'tok-glpat-supersecret-12345';
+
+describe('unresolved recipe persistence', () => {
+  const originalEnv = process.env;
+  const originalFetch = globalThis.fetch;
+  let tmpDir: string;
+  let dataDir: string;
+  let recipePath: string;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    tmpDir = mkdtempSync(join(tmpdir(), 'conhost-save-unresolved-'));
+    dataDir = join(tmpDir, 'data');
+    recipePath = join(tmpDir, 'recipe.json');
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+    globalThis.fetch = originalFetch;
+    try { rmSync(tmpDir, { recursive: true, force: true }); } catch { /* noop */ }
+  });
+
+  function writeSecretRecipe(): void {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Secret Test',
+      agent: { systemPrompt: 'be helpful' },
+      mcpServers: {
+        gitlab: {
+          command: 'node',
+          env: { GITLAB_PERSONAL_ACCESS_TOKEN: '${CONHOST_TEST_SECRET}' },
+        },
+      },
+    }), 'utf-8');
+  }
+
+  test('resolved recipe carries the secret in memory; persistable keeps the ${VAR} literal', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    expect((recipe.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN).toBe(SECRET);
+    expect((persistable.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN)
+      .toBe('${CONHOST_TEST_SECRET}');
+  });
+
+  test('the saved .recipe.json never contains the substituted secret', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    const onDisk = readFileSync(join(dataDir, '.recipe.json'), 'utf-8');
+    expect(onDisk).not.toContain(SECRET);
+    expect(onDisk).toContain('${CONHOST_TEST_SECRET}');
+    expect(JSON.parse(onDisk)[SAVED_RECIPE_UNRESOLVED_KEY]).toBe(true);
+  });
+
+  test('loadSavedRecipe re-resolves against the CURRENT environment (secret rotation)', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    process.env.CONHOST_TEST_SECRET = 'tok-rotated-67890';
+    const resumed = await loadSavedRecipe(dataDir);
+    expect(resumed).not.toBeNull();
+    expect((resumed!.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN)
+      .toBe('tok-rotated-67890');
+  });
+
+  test('loadSavedRecipe throws (not null) when a required var disappeared from the environment', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+
+    delete process.env.CONHOST_TEST_SECRET;
+    await expect(loadSavedRecipe(dataDir)).rejects.toThrow(/CONHOST_TEST_SECRET/);
+  });
+
+  test('saveRecipe writes the snapshot with mode 0600, and chmods a pre-existing looser file', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const { persistable } = await loadRecipeDetailed(recipePath);
+
+    saveRecipe(dataDir, persistable);
+    const path = join(dataDir, '.recipe.json');
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+
+    // Legacy deployments have a world-readable resolved snapshot; an
+    // overwrite must tighten it even though writeFileSync's mode only
+    // applies at creation.
+    chmodSync(path, 0o644);
+    expect(statSync(path).mode & 0o777).toBe(0o644);
+    saveRecipe(dataDir, persistable);
+    expect(statSync(path).mode & 0o777).toBe(0o600);
+  });
+
+  test('round-trip with no ${} patterns is a faithful no-op resolution', async () => {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Plain',
+      description: 'no env refs',
+      agent: { systemPrompt: 'hello', model: 'claude-opus-4-6' },
+    }), 'utf-8');
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    saveRecipe(dataDir, persistable);
+    const resumed = await loadSavedRecipe(dataDir);
+    expect(resumed).not.toBeNull();
+    expect(resumed!.name).toBe('Plain');
+    expect(resumed!.agent.systemPrompt).toBe(recipe.agent.systemPrompt);
+    expect(resumed!.agent.model).toBe('claude-opus-4-6');
+  });
+
+  test('relative fleet child recipe paths are persisted absolute (resume has no source base)', async () => {
+    writeFileSync(recipePath, JSON.stringify({
+      name: 'Fleet Parent',
+      agent: { systemPrompt: 'parent' },
+      modules: {
+        fleet: { children: [{ name: 'child-a', recipe: 'child.json' }] },
+      },
+    }), 'utf-8');
+
+    const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+    const expected = resolve(tmpDir, 'child.json');
+    expect((recipe.modules!.fleet as any).children[0].recipe).toBe(expected);
+    expect(((persistable.modules as any).fleet.children[0]).recipe).toBe(expected);
+
+    saveRecipe(dataDir, persistable);
+    const resumed = await loadSavedRecipe(dataDir);
+    expect((resumed!.modules!.fleet as any).children[0].recipe).toBe(expected);
+  });
+
+  describe('URL systemPrompt', () => {
+    test('persisted as the URL and re-fetched on resume, picking up prompt updates', async () => {
+      let fetchCount = 0;
+      globalThis.fetch = (async (input: any) => {
+        expect(String(input)).toBe('https://prompts.example/agent.txt');
+        fetchCount++;
+        return new Response(fetchCount === 1 ? 'FETCHED PROMPT v1' : 'FETCHED PROMPT v2');
+      }) as typeof fetch;
+
+      writeFileSync(recipePath, JSON.stringify({
+        name: 'URL Prompt',
+        agent: { systemPrompt: 'https://prompts.example/agent.txt' },
+      }), 'utf-8');
+
+      const { recipe, persistable } = await loadRecipeDetailed(recipePath);
+      expect(recipe.agent.systemPrompt).toBe('FETCHED PROMPT v1');
+      expect((persistable.agent as any).systemPrompt).toBe('https://prompts.example/agent.txt');
+
+      saveRecipe(dataDir, persistable);
+      const onDisk = readFileSync(join(dataDir, '.recipe.json'), 'utf-8');
+      expect(onDisk).not.toContain('FETCHED PROMPT');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed!.agent.systemPrompt).toBe('FETCHED PROMPT v2');
+      expect(fetchCount).toBe(2);
+    });
+  });
+
+  describe('legacy resolved snapshots (no marker)', () => {
+    test('load verbatim with no substitution', async () => {
+      // Simulate an older host's save: fully resolved, no marker.
+      const legacy = {
+        name: 'Legacy',
+        agent: { systemPrompt: 'resolved prompt' },
+        mcpServers: { gitlab: { command: 'node', env: { TOKEN: SECRET } } },
+      };
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), JSON.stringify(legacy, null, 2) + '\n', 'utf-8');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed).not.toBeNull();
+      expect((resumed!.mcpServers as any).gitlab.env.TOKEN).toBe(SECRET);
+    });
+
+    test('a surviving literal ${...} in prose does not hard-fail the load', async () => {
+      delete process.env.DEFINITELY_NOT_SET_ANYWHERE;
+      const legacy = {
+        name: 'Legacy Prose',
+        agent: {
+          systemPrompt: 'To configure, set ${DEFINITELY_NOT_SET_ANYWHERE} in your .env file.',
+        },
+      };
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), JSON.stringify(legacy) + '\n', 'utf-8');
+
+      const resumed = await loadSavedRecipe(dataDir);
+      expect(resumed).not.toBeNull();
+      expect(resumed!.agent.systemPrompt).toContain('${DEFINITELY_NOT_SET_ANYWHERE}');
+    });
+
+    test('corrupt JSON still returns null rather than throwing', async () => {
+      mkdirSync(dataDir, { recursive: true });
+      writeFileSync(join(dataDir, '.recipe.json'), '{not json', 'utf-8');
+      expect(await loadSavedRecipe(dataDir)).toBeNull();
+    });
+
+    test('missing snapshot returns null', async () => {
+      expect(await loadSavedRecipe(dataDir)).toBeNull();
+    });
+  });
+
+  test('loadRecipe wrapper still returns the resolved recipe', async () => {
+    process.env.CONHOST_TEST_SECRET = SECRET;
+    writeSecretRecipe();
+    const recipe = await loadRecipe(recipePath);
+    expect((recipe.mcpServers as any).gitlab.env.GITLAB_PERSONAL_ACCESS_TOKEN).toBe(SECRET);
+  });
+});

package/test/recipe-source-only.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test';
+import { validateRecipe } from '../src/recipe.js';
+import { buildFrameworkStrategy } from '../src/framework-strategy.js';
+
+function recipe(strategy: Record<string, unknown>) {
+  return {
+    name: 'source-only-test',
+    agent: { systemPrompt: 'sys', strategy: { type: 'autobiographical', ...strategy } },
+  };
+}
+
+describe('compressionSourceOnly recipe flag', () => {
+  test('preserves the flag through validation', () => {
+    expect(validateRecipe(recipe({ compressionSourceOnly: true }))
+      .agent.strategy?.compressionSourceOnly).toBe(true);
+    expect(validateRecipe(recipe({ compressionSourceOnly: false }))
+      .agent.strategy?.compressionSourceOnly).toBe(false);
+    // absent stays undefined — every other resident is unaffected
+    expect(validateRecipe(recipe({})).agent.strategy?.compressionSourceOnly).toBeUndefined();
+  });
+
+  test('rejects a non-boolean value', () => {
+    expect(() => validateRecipe(recipe({ compressionSourceOnly: 'yes' })))
+      .toThrow(/compressionSourceOnly/);
+    expect(() => validateRecipe(recipe({ compressionSourceOnly: 1 })))
+      .toThrow(/compressionSourceOnly/);
+  });
+
+  test('plumbs through PASSTHROUGH_KEYS into the built strategy config', () => {
+    const parsed = validateRecipe(recipe({ compressionSourceOnly: true, summaryParticipant: 'mythos' }));
+    const built = buildFrameworkStrategy(parsed, 'claude-fable-5', 'UTC');
+    // buildFrameworkStrategy copies PASSTHROUGH_KEYS onto the strategy options;
+    // the flag must reach the AutobiographicalStrategy config.
+    const cfg = (built as unknown as { config?: Record<string, unknown> }).config
+      ?? (built as unknown as Record<string, unknown>);
+    expect(cfg.compressionSourceOnly).toBe(true);
+  });
+});

package/test/release-changelog.test.ts

@@ -0,0 +1,202 @@
+// Black-box coverage of scripts/release-changelog.ts: each case runs the
+// real script in a throwaway directory, so assembly, validation, and the
+// deletion of consumed fragments are all exercised exactly as `npm version`
+// would run them.
+import { test } from "bun:test";
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT = fileURLToPath(
+  new URL("../scripts/release-changelog.ts", import.meta.url),
+);
+
+const BASE_CHANGELOG = [
+  "# Changelog",
+  "",
+  "Intro that mentions ## Unreleased inline, which must not count as a heading.",
+  "",
+  "## Unreleased",
+  "",
+  "## 1.0.0 — 2026-01-01",
+  "",
+  "### Fixed",
+  "",
+  "- Old entry.",
+  "",
+].join("\n");
+
+interface Fixture {
+  version?: string;
+  changelog?: string;
+  fragments?: Record<string, string>;
+}
+
+function setup(f: Fixture): string {
+  const dir = mkdtempSync(join(tmpdir(), "release-changelog-"));
+  writeFileSync(
+    join(dir, "package.json"),
+    JSON.stringify({ name: "fixture", version: f.version ?? "1.1.0" }),
+  );
+  writeFileSync(join(dir, "CHANGELOG.md"), f.changelog ?? BASE_CHANGELOG);
+  mkdirSync(join(dir, "changelog.d"));
+  writeFileSync(join(dir, "changelog.d", "README.md"), "# Pending fragments\n");
+  for (const [name, body] of Object.entries(f.fragments ?? {})) {
+    const path = join(dir, "changelog.d", name);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, body);
+  }
+  return dir;
+}
+
+function run(dir: string): { status: number; stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync(process.execPath, [SCRIPT], {
+      cwd: dir,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    return { status: 0, stdout, stderr: "" };
+  } catch (e) {
+    const err = e as { status: number; stdout?: string; stderr?: string };
+    return { status: err.status, stdout: err.stdout ?? "", stderr: err.stderr ?? "" };
+  }
+}
+
+function section(text: string, version: string): string {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.startsWith(`## ${version} — `));
+  assert.notEqual(start, -1, `no '## ${version}' section in:\n${text}`);
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((l) => l.startsWith("## "));
+  return rest.slice(0, end === -1 ? undefined : end).join("\n").trim();
+}
+
+const changelog = (dir: string) => readFileSync(join(dir, "CHANGELOG.md"), "utf8");
+const pending = (dir: string) => readdirSync(join(dir, "changelog.d")).sort();
+
+test("folds fragments into a versioned section in canonical order and deletes them", () => {
+  const dir = setup({
+    fragments: {
+      "z-later.fixed.md": "- Fixed thing.\n",
+      "a-first.added.md": "- Added thing,\n  continued on an indented line.\n",
+      "m.breaking.md": "- **Module authors:** breaking thing.\n",
+    },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  const text = changelog(dir);
+  assert.equal(
+    section(text, "1.1.0"),
+    [
+      "### Breaking",
+      "",
+      "- **Module authors:** breaking thing.",
+      "",
+      "### Added",
+      "",
+      "- Added thing,",
+      "  continued on an indented line.",
+      "",
+      "### Fixed",
+      "",
+      "- Fixed thing.",
+    ].join("\n"),
+  );
+  assert.match(text, /^## Unreleased\n\n## 1\.1\.0 — \d{4}-\d{2}-\d{2}\n/m, "fresh empty Unreleased above the cut");
+  assert.ok(text.startsWith("# Changelog\n\nIntro that mentions"), "file header preserved");
+  assert.equal(section(text, "1.0.0"), "### Fixed\n\n- Old entry.", "older section untouched");
+  assert.deepEqual(pending(dir), ["README.md"], "consumed fragments deleted, README kept");
+});
+
+test("merges fragments into directly-filed Unreleased entries, reordering subsections canonically", () => {
+  const dir = setup({
+    changelog: BASE_CHANGELOG.replace(
+      "## Unreleased\n",
+      "## Unreleased\n\n### Fixed\n\n- Manual fix.\n\n### Added\n\n- Manual add.\n",
+    ),
+    fragments: { "x.fixed.md": "- Fragment fix.\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(
+    section(changelog(dir), "1.1.0"),
+    "### Added\n\n- Manual add.\n\n### Fixed\n\n- Manual fix.\n\n- Fragment fix.",
+  );
+});
+
+test("breaking fragments join an audience-qualified Breaking heading", () => {
+  const dir = setup({
+    changelog: BASE_CHANGELOG.replace(
+      "## Unreleased\n",
+      "## Unreleased\n\n### Fixed\n\n- Manual fix.\n\n### Breaking (module authors only)\n\n- Manual break.\n",
+    ),
+    fragments: { "b.breaking.md": "- Fragment break.\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(
+    section(changelog(dir), "1.1.0"),
+    "### Breaking (module authors only)\n\n- Manual break.\n\n- Fragment break.\n\n### Fixed\n\n- Manual fix.",
+  );
+});
+
+test("accepts nested bullets and multi-line continuations", () => {
+  const dir = setup({
+    fragments: { "n.fixed.md": "- one\n  - nested\n  more text\n- two\n" },
+  });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(section(changelog(dir), "1.1.0"), "### Fixed\n\n- one\n  - nested\n  more text\n- two");
+});
+
+test("accepts bullet content that merely resembles headings or rules", () => {
+  const body = "- **Module authors:** bold opener.\n- -1 is now the sentinel.\n- #123 is referenced inline.\n- ***emphasis*** then text.\n";
+  const dir = setup({ fragments: { "r.fixed.md": body } });
+  const r = run(dir);
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(section(changelog(dir), "1.1.0"), `### Fixed\n\n${body.trim()}`);
+});
+
+const refusals: Array<[string, Fixture, RegExp]> = [
+  ["nothing to release", {}, /nothing to release as 1\.1\.0/],
+  ["duplicate version section", { version: "1.0.0", fragments: { "a.fixed.md": "- x\n" } }, /'## 1\.0\.0' section already exists/],
+  ["unrecognized category suffix", { fragments: { "oops.md": "- x\n" } }, /changelog\.d\/oops\.md: unrecognized file/],
+  ["stray non-markdown file", { fragments: { "notes.txt": "hi\n", "a.fixed.md": "- x\n" } }, /changelog\.d\/notes\.txt: unrecognized file/],
+  ["empty fragment", { fragments: { "e.fixed.md": "\n" } }, /changelog\.d\/e\.fixed\.md: empty fragment/],
+  ["fragment nested under a branch-name directory", { fragments: { "fix/foo.fixed.md": "- x\n", "a.fixed.md": "- y\n" } }, /changelog\.d\/fix: not a file/],
+  ["plain prose", { fragments: { "p.fixed.md": "prose only\n" } }, /offending line: 'prose only'/],
+  ["prose after a valid bullet", { fragments: { "p.fixed.md": "- ok\nrogue prose\n" } }, /offending line: 'rogue prose'/],
+  ["top-level heading after a bullet", { fragments: { "h.fixed.md": "- ok\n\n## 9.9.9 — fake\n" } }, /offending line: '## 9\.9\.9 — fake'/],
+  ["indented ATX heading", { fragments: { "h.fixed.md": "- ok\n  ## 8.8.8 — injected\n  - beneath\n" } }, /offending line: '  ## 8\.8\.8 — injected'/],
+  ["indented setext underline / rule", { fragments: { "s.fixed.md": "- ok\n  ---\n" } }, /offending line: '  ---'/],
+  ["spaced thematic break shaped like a bullet", { fragments: { "s.fixed.md": "- ok\n- - -\n" } }, /offending line: '- - -'/],
+  ["asterisk thematic break with spaces", { fragments: { "s.fixed.md": "- ok\n* * *\n" } }, /offending line: '\* \* \*'/],
+  ["rule as bullet content", { fragments: { "s.fixed.md": "- ---\n" } }, /offending line: '- ---'/],
+  ["heading as bullet content", { fragments: { "h.fixed.md": "- ## 9.9.9 — embedded heading\n" } }, /offending line: '- ## 9\.9\.9 — embedded heading'/],
+  ["heading as nested bullet content", { fragments: { "h.fixed.md": "- ok\n  - ### nested heading\n" } }, /offending line: '  - ### nested heading'/],
+  ["tab-indented continuation", { fragments: { "t.fixed.md": "- ok\n\tcontinued\n" } }, /offending line: '\tcontinued'/],
+  ["no Unreleased heading", { changelog: "# Changelog\n\n## 1.0.0 — 2026-01-01\n\n- x\n", fragments: { "a.fixed.md": "- x\n" } }, /no '## Unreleased' section/],
+  ["two Unreleased headings", { changelog: BASE_CHANGELOG + "\n## Unreleased\n\n- stranded\n", fragments: { "a.fixed.md": "- x\n" } }, /2 '## Unreleased' headings/],
+];
+
+for (const [name, fixture, message] of refusals) {
+  test(`refuses ${name} without touching anything`, () => {
+    const dir = setup(fixture);
+    const before = { changelog: changelog(dir), pending: pending(dir) };
+    const r = run(dir);
+    assert.equal(r.status, 1, `expected refusal, got exit ${r.status}:\n${r.stdout}${r.stderr}`);
+    assert.match(r.stderr, message);
+    assert.equal(changelog(dir), before.changelog, "CHANGELOG.md must be untouched");
+    assert.deepEqual(pending(dir), before.pending, "no fragment may be deleted on refusal");
+  });
+}

package/test/subagent-prose-routing.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Ephemeral subagents must inherit the caller's proseRouting mode.
+ *
+ * AF's Agent defaults proseRouting to 'locus' (ambient locus capture
+ * publishes plain prose to the open channel). Before this fix,
+ * SubagentModule never passed proseRouting to createEphemeralAgent, so a
+ * resident running proseRouting 'disabled' still spawned divers whose
+ * between-tool-calls prose leaked into its live Zulip topic as parent
+ * speech — field-confirmed on a deployed resident, 2026-08-26, and
+ * reproduced again after the recipe adopted 'disabled' (the recipe value
+ * reached only the resident, never the divers).
+ *
+ * Harness follows subagent-async-timeout.test.ts: real framework + mock
+ * membrane, runEphemeralToCompletion stubbed — here to capture the
+ * ephemeral Agent it receives so the test can read its proseRouting.
+ */
+import { describe, test, expect } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { AgentFramework } from '@animalabs/agent-framework';
+import type { Module, ToolCall } from '@animalabs/agent-framework';
+import { Membrane, MockAdapter, NativeFormatter } from '@animalabs/membrane';
+import { SubagentModule } from '../src/modules/subagent-module.js';
+
+async function makeHarness(parentProseRouting?: 'locus' | 'explicit' | 'hybrid' | 'disabled') {
+  const tmpDir = mkdtempSync(join(tmpdir(), 'sub-prose-'));
+  const adapter = new MockAdapter({ defaultResponse: 'ok' });
+  const membrane = new Membrane(adapter, { formatter: new NativeFormatter() });
+  const subagent = new SubagentModule({
+    parentAgentName: 'parent',
+    defaultModel: 'mock',
+    defaultMaxTokens: 256,
+    maxRetries: 0,
+  });
+  const framework = await AgentFramework.create({
+    storePath: join(tmpDir, 'store'),
+    membrane,
+    agents: [{
+      name: 'parent',
+      model: 'mock',
+      systemPrompt: 'parent',
+      maxTokens: 256,
+      ...(parentProseRouting !== undefined ? { proseRouting: parentProseRouting } : {}),
+    }],
+    modules: [subagent as unknown as Module],
+  });
+  subagent.setFramework(framework);
+
+  // Capture the ephemeral Agent handed to the run loop; resolve immediately.
+  let captured: { proseRouting?: string; name?: string } | null = null;
+  const fw = framework as unknown as {
+    runEphemeralToCompletion: (agent: unknown, ctxMgr: unknown) => Promise<{ speech: string; toolCallsCount: number }>;
+  };
+  fw.runEphemeralToCompletion = async (agent: unknown) => {
+    captured = agent as { proseRouting?: string; name?: string };
+    return { speech: 'done', toolCallsCount: 0 };
+  };
+
+  const cleanup = async () => {
+    await framework.stop().catch(() => {});
+    rmSync(tmpDir, { recursive: true, force: true });
+  };
+  return { subagent, getCaptured: () => captured, cleanup };
+}
+
+function spawnCall(): ToolCall {
+  return {
+    id: 'tc-1',
+    name: 'spawn',
+    callerAgentName: 'parent',
+    input: {
+      name: 'probe',
+      systemPrompt: 'you are a probe',
+      task: 'probe the harness',
+      sync: true,
+    },
+  } as unknown as ToolCall;
+}
+
+describe('subagent prose-routing inheritance', () => {
+  test("spawned subagent inherits the parent's proseRouting 'disabled'", async () => {
+    const h = await makeHarness('disabled');
+    try {
+      const result = await h.subagent.handleToolCall(spawnCall());
+      if (!result.success) console.error('SPAWN ERROR:', result.error);
+      expect(result.success).toBe(true);
+      expect(h.getCaptured()).not.toBeNull();
+      expect(h.getCaptured()!.proseRouting).toBe('disabled');
+    } finally {
+      await h.cleanup();
+    }
+  });
+
+  test("parent without explicit proseRouting yields AF's default on the child ('locus')", async () => {
+    const h = await makeHarness(undefined);
+    try {
+      const result = await h.subagent.handleToolCall(spawnCall());
+      if (!result.success) console.error('SPAWN ERROR:', result.error);
+      expect(result.success).toBe(true);
+      // Parent's resolved mode is AF's default 'locus'; inheritance passes it
+      // through explicitly — same value the child would default to, asserted
+      // so a future AF default change keeps parent and child in lockstep.
+      expect(h.getCaptured()!.proseRouting).toBe('locus');
+    } finally {
+      await h.cleanup();
+    }
+  });
+});

package/test/workspace-mounts.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+import { resolve } from 'node:path';
+import { buildWorkspaceMounts } from '../src/workspace-mounts.js';
+
+/**
+ * Contract tests for the shared mount builder. validateRecipe's instructions
+ * cross-check reasons over this exact output, so these pin the properties the
+ * validator depends on — most importantly that `_config` is NOT
+ * auto-materialized (agent edits stay Chronicle-side between branch-changing
+ * commands), which is why the validator rejects it as an instructions path.
+ */
+describe('buildWorkspaceMounts', () => {
+  test('workspace: false disables mounts entirely', () => {
+    expect(buildWorkspaceMounts(false, '/store')).toBeNull();
+  });
+
+  test('implicit default (omitted or true): input ro + products rw, neither auto-materialized', () => {
+    for (const ws of [undefined, true as const]) {
+      const mounts = buildWorkspaceMounts(ws, '/store')!;
+      expect(mounts.map((m) => m.name)).toEqual(['input', 'products']);
+      const [input, products] = mounts;
+      expect(input.mode).toBe('read-only');
+      expect(products.mode).toBe('read-write');
+      expect(input.autoMaterialize).toBeUndefined();
+      expect(products.autoMaterialize).toBeUndefined();
+    }
+  });
+
+  test('explicit mounts pass through declared fields and default mode/watch', () => {
+    const mounts = buildWorkspaceMounts({
+      mounts: [
+        { name: 'instructions', path: './instructions', autoMaterialize: true },
+        { name: 'refs', path: './refs', mode: 'read-only', watch: 'always' },
+      ],
+    }, '/store')!;
+    expect(mounts[0]).toMatchObject({
+      name: 'instructions',
+      path: resolve('./instructions'),
+      mode: 'read-write', // defaulted
+      watch: 'never', // defaulted (no chokidar by default)
+      autoMaterialize: true,
+    });
+    expect(mounts[1]).toMatchObject({ mode: 'read-only', watch: 'always' });
+    expect(mounts[1].autoMaterialize).toBeUndefined();
+  });
+
+  test('_config mount (configMount: true) is read-write and NOT auto-materialized', () => {
+    // THE contract behind rejecting `_config/...` as an instructions path:
+    // the host materializes this mount only after branch-changing commands,
+    // never on ordinary agent writes. If this test starts failing because
+    // `_config` gained autoMaterialize, revisit the validator's rejection.
+    const mounts = buildWorkspaceMounts({ mounts: [], configMount: true }, '/store')!;
+    const config = mounts.find((m) => m.name === '_config')!;
+    expect(config).toBeDefined();
+    expect(config.mode).toBe('read-write');
+    expect(config.autoMaterialize).toBeUndefined();
+    expect(config.path).toBe(resolve('/store/config'));
+    expect(config.watch).toBe('always');
+  });
+
+  test('configMount composes with the implicit default mounts only in object form', () => {
+    // Matches the host: `workspace: true` cannot request the config mount.
+    const objForm = buildWorkspaceMounts({ mounts: undefined as never, configMount: true }, '/s');
+    expect((objForm ?? []).some((m) => m.name === '_config')).toBe(true);
+    const boolForm = buildWorkspaceMounts(true, '/s')!;
+    expect(boolForm.some((m) => m.name === '_config')).toBe(false);
+  });
+});

package/web/src/App.tsx

@@ -2065,6 +2065,7 @@ const COMMANDS: CommandHint[] = [
   { name: '/restore', blurb: 'switch to checkpoint' },
   { name: '/undo', blurb: 'revert before last agent turn' },
   { name: '/redo', blurb: 're-apply last undone action' },
+  { name: '/nudge', blurb: 'run inference on current context, no new events' },
   { name: '/history', blurb: 'recent messages' },
   { name: '/lessons', blurb: 'list active lessons' },
   { name: '/export', blurb: 'export lessons to ./output/' },