mandrel 1.85.0 → 1.87.0

package/.agents/instructions.md

@@ -334,6 +334,13 @@ budget grounds.
   spawns (search, doc regeneration, lint, log triage) and keep
   **implementation and design** work on the default capability; name no
   specific model — let the host and operator own the concrete mapping.
+  **Depth compounds the cost.** Sub-agents now carry the `Agent` tool and
+  can nest further (verified depth 2, announced max depth 5; see
+  [#2870](https://github.com/dsj1984/mandrel/issues/2870)), so this
+  spend-per-spawn caution is not one-level — **every** nesting level
+  re-pays the full always-loaded context. Weigh the whole subtree's cost,
+  not just the immediate spawn, before opening a deeper orchestration
+  level, and stay within the supported depth envelope.
 - **Anti-Laziness:** NEVER use placeholder comments like
   `// ... existing code ...`, `/* rest of file */`, or
   `// implementation here`. You MUST output the ENTIRE file or the ENTIRE

package/.agents/rules/git-conventions.md

@@ -120,6 +120,51 @@ rejected by `pre-push` hooks):
       (`--no-errors-on-unmatched` or equivalent) before escalating via
       `agent::blocked`.
 
+## Local checkout hygiene
+
+**Invariant: the delivering flow owns tidying the local checkout — reaping its
+own merged refs and fast-forwarding the base branch. `/git-cleanup` is a
+recovery tool, not a routine chore.**
+
+Every flow that lands work — `/deliver` (Epic and standalone-Story paths),
+`/git-deliver` — is responsible for leaving the local checkout tidy without
+operator intervention:
+
+- **Fast-forwarding the base branch is owned by the flow.** The standalone
+  multi-Story path fast-forwards `main` itself in its summary phase (via
+  `git-cleanup.js --fast-forward-main --execute --yes`); the Epic path
+  fast-forwards `epic/<id>` / `main` on its merge-and-reap beat. No workflow
+  ends by telling the operator to "run `/git-cleanup` afterwards to catch up".
+- **Reaping merged local refs is owned by the flow's next boot.** `/plan` and
+  `/git-deliver` open with a **protected boot sweep**
+  (`boot-sweep.js`) that fast-forwards `main`, prunes stale remote-tracking
+  refs, and reaps every local branch whose PR is already merged — skipping any
+  candidate with unpushed work, a dirty worktree, or a still-open parent
+  ticket. A branch a flow leaves behind (e.g. a `/git-deliver` feature branch
+  whose PR merges out of band) is therefore reaped automatically at the next
+  workflow boot, not left for the operator to sweep by hand. `boot-sweep.js`
+  defaults its `--include` glob to `story-*` — a bare invocation only sweeps
+  Story branches; `/plan` and `/git-deliver` widen the scope to their own
+  branch namespaces (`epic/*`, `feat/*`, `fix/*`, `chore/*`, `docs/*`,
+  `refactor/*`) by passing `--include` explicitly at their boot call site.
+  A branch the planner detects only via the weaker content-equivalence
+  signal (`detectedBy: 'content-merged'`, Story #4395's
+  `git merge-tree --write-tree` probe — content already landed in the base
+  branch by another route, such as a squash-merged Epic PR, with no merged
+  PR or git ancestry of its own) is **never** reaped by the boot sweep: it
+  is report-only, surfaced under `contentMerged` in the result envelope and
+  a routing hint in the summary line (Story #4396), so the operator can
+  send it to `/git-cleanup` for a confirmed, eyeballed reap.
+- **`/git-cleanup` is recovery, not routine.** Run it by hand only to recover
+  an unusual state the automated hygiene does not cover — triaging stashes,
+  reaping across non-standard branch namespaces, or `--remote` pruning after a
+  force-push diverged a tip. It is **not** the expected way to keep `main`
+  current or to clear merged branches after a normal delivery; the delivering
+  flows already own that. If you find yourself reaching for `/git-cleanup`
+  after every routine `/deliver` or `/git-deliver` run, that is a signal the
+  owning flow's hygiene step regressed — fix the flow, do not codify the manual
+  sweep.
+
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so

package/.agents/scripts/boot-sweep.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * boot-sweep.js — protected boot-sweep CLI (Story #4373).
+ *
+ * A thin, non-interactive wrapper over the scope-agnostic
+ * [`sweepMergedBranches`](./lib/single-story-sweep.js) engine, exposed so
+ * workflow prose can invoke a *protected* boot sweep directly. Unlike the
+ * plain `git-cleanup.js --branches` phase (which reaps every merged
+ * candidate the planner surfaces), this surface always applies the
+ * `evaluateProtection` partition — a merged branch with unpushed work, a
+ * dirty worktree, or a still-open parent Story ticket is skipped, not
+ * reaped.
+ *
+ * The sweep is best-effort: any failure (lock contention, git/gh error)
+ * is swallowed and reported in the result envelope, never thrown, so a
+ * caller can wire it into a boot path without risking the host run.
+ *
+ * **Content-merged branches are report-only (Story #4396).** The planner
+ * also surfaces branches whose content already landed in the base branch
+ * by another route (a squash-merged Epic PR, a renamed head, a manual
+ * squash merge) via `detectedBy: 'content-merged'` (Story #4395's
+ * `git merge-tree --write-tree` probe) — a weaker signal than a merged PR
+ * or git ancestry, since no CI/GitHub merge check ever validated that
+ * branch's exact diff. This sweep never reaps on that signal alone; it
+ * surfaces the branches under `contentMerged` in the result envelope (and
+ * a routing hint in the human summary) so the operator can send them to
+ * `/git-cleanup` for a confirmed, eyeballed reap.
+ *
+ * Usage:
+ *   node .agents/scripts/boot-sweep.js [--include <glob>...] \
+ *     [--exclude <glob>...] [--current <branch>] [--base <branch>] \
+ *     [--no-fast-forward] [--json]
+ *
+ * Defaults: `--include story-*`, fast-forward the base branch on.
+ * Exit code is always 0 — a boot sweep never fails its host.
+ */
+
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+
+import { runAsCli } from './lib/cli-utils.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { createProvider } from './lib/provider-factory.js';
+import { buildProtectionCtx } from './lib/single-story-sweep/protection-ctx.js';
+import { sweepMergedBranches } from './lib/single-story-sweep.js';
+
+const HELP = `Usage: node .agents/scripts/boot-sweep.js [options]
+
+Runs the protected merged-branch boot sweep non-interactively: reaps every
+local branch whose PR is MERGED and whose HEAD matches the merged headRefOid,
+skipping any candidate the protection partition flags (unpushed work, dirty
+worktree, still-open parent Story), then fast-forwards the base branch.
+Branches detected only via the weaker content-equivalence signal
+(detectedBy: 'content-merged') are never reaped here — they are reported
+under "contentMerged" (and a routing hint in the summary line) for the
+operator to send to /git-cleanup.
+
+Options:
+  --include <glob>     Branch glob to sweep (repeatable). Default: story-*
+  --exclude <glob>     Branch glob to exclude (repeatable).
+  --current <branch>   A branch to always exclude (e.g. the active story).
+  --base <branch>      Base branch to fast-forward. Default: project baseBranch.
+  --no-fast-forward    Skip the base-branch fast-forward step.
+  --json               Emit the result envelope as JSON.
+`;
+
+/**
+ * Run the protected boot sweep. Best-effort: swallows any error and
+ * returns the sweep envelope so no caller can be blocked by a failure.
+ *
+ * DI-friendly: `injectedConfig` / `injectedProvider` let a caller (e.g.
+ * `epic-deliver-prepare.js`) reuse an already-resolved config + provider,
+ * and `injectedSweep` swaps the engine for unit tests.
+ *
+ * @param {{
+ *   cwd?: string,
+ *   base?: string,
+ *   include?: string[],
+ *   exclude?: string[],
+ *   current?: string,
+ *   fastForward?: boolean,
+ *   injectedConfig?: object,
+ *   injectedProvider?: object,
+ *   injectedSweep?: Function,
+ *   logger?: { info?: Function, warn?: Function },
+ * }} [args]
+ * @returns {Promise<object>} the {@link sweepMergedBranches} envelope.
+ */
+export async function runBootSweep({
+  cwd,
+  base,
+  include,
+  exclude,
+  current,
+  fastForward = true,
+  injectedConfig,
+  injectedProvider,
+  injectedSweep,
+  logger = Logger,
+} = {}) {
+  const root = path.resolve(cwd ?? PROJECT_ROOT);
+  try {
+    // Config/provider resolution is inside the try so a malformed
+    // `.agentrc.json` (or a provider-construction throw) degrades to the
+    // swallowed `ok:false` envelope below rather than propagating and
+    // exiting non-zero — the "host continues, exit 0" boot-sweep contract
+    // must hold even when config resolution is the thing that fails.
+    const config = injectedConfig ?? resolveConfig({ cwd: root });
+    const provider = injectedProvider ?? createProvider(config);
+    const baseBranch = base ?? config.project?.baseBranch ?? 'main';
+
+    const includeGlobs =
+      Array.isArray(include) && include.length > 0 ? include : ['story-*'];
+    const excludeGlobs = Array.isArray(exclude) ? [...exclude] : [];
+    if (typeof current === 'string' && current.length > 0) {
+      excludeGlobs.push(current);
+    }
+
+    const tempRoot = config?.project?.paths?.tempRoot ?? 'temp';
+    const lockPath = path.resolve(root, tempRoot, 'boot-sweep.lock');
+    const lockTimeoutMs =
+      config.delivery?.worktreeIsolation?.sweepLockMs ?? 60_000;
+
+    const sweepFn = injectedSweep ?? sweepMergedBranches;
+    return await sweepFn({
+      cwd: root,
+      baseBranch,
+      include: includeGlobs,
+      exclude: excludeGlobs,
+      fastForward,
+      logTag: '[boot-sweep]',
+      logger: {
+        info: (m) => logger.info?.(m),
+        warn: (m) => logger.warn?.(m),
+      },
+      protectionCtx: buildProtectionCtx({ cwd: root, provider }),
+      lockPath,
+      lockTimeoutMs,
+    });
+  } catch (err) {
+    const msg = err?.message ?? String(err);
+    logger.warn?.(`[boot-sweep] sweep threw (host continues): ${msg}`);
+    return {
+      ok: false,
+      skipped: true,
+      error: msg,
+      candidates: 0,
+      localDeleted: 0,
+      remoteDeleted: 0,
+      protected: [],
+      contentMerged: [],
+      failures: [],
+    };
+  }
+}
+
+/**
+ * Build the human-readable one-line summary for a sweep result envelope.
+ * Exported for unit tests (Story #4396). A zero `contentMerged` count keeps
+ * the pre-Story #4396 line byte-identical (silent no-op summary); a nonzero
+ * count appends a routing hint pointing the operator at `/git-cleanup`.
+ *
+ * @param {{ localDeleted: number, remoteDeleted: number, protected?: Array, contentMerged?: Array }} result
+ * @returns {string}
+ */
+export function buildSummaryLine(result) {
+  const protectedCount = result.protected?.length ?? 0;
+  const contentMergedCount = result.contentMerged?.length ?? 0;
+  const contentMergedSuffix =
+    contentMergedCount > 0
+      ? `; ${contentMergedCount} content-merged branch(es) left for /git-cleanup`
+      : '';
+  return `[boot-sweep] reaped ${result.localDeleted} local + ${result.remoteDeleted} remote; protected ${protectedCount}${contentMergedSuffix}.`;
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: {
+      base: { type: 'string' },
+      cwd: { type: 'string' },
+      include: { type: 'string', multiple: true, default: [] },
+      exclude: { type: 'string', multiple: true, default: [] },
+      current: { type: 'string' },
+      'no-fast-forward': { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+  });
+
+  if (values.help) {
+    Logger.info(HELP);
+    return;
+  }
+
+  const result = await runBootSweep({
+    cwd: typeof values.cwd === 'string' ? values.cwd : undefined,
+    base: typeof values.base === 'string' ? values.base : undefined,
+    include: Array.isArray(values.include) ? values.include : [],
+    exclude: Array.isArray(values.exclude) ? values.exclude : [],
+    current: typeof values.current === 'string' ? values.current : undefined,
+    fastForward: values['no-fast-forward'] !== true,
+  });
+
+  if (values.json) {
+    Logger.info(JSON.stringify(result, null, 2));
+  } else {
+    Logger.info(buildSummaryLine(result));
+  }
+}
+
+runAsCli(import.meta.url, main, { source: 'boot-sweep' });

package/.agents/scripts/epic-deliver-prepare.js

@@ -36,6 +36,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 
+import { runBootSweep } from './boot-sweep.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
 import { currentBranch as gitCurrentBranch } from './lib/git-branch-lifecycle.js';
@@ -218,6 +219,49 @@ async function runPreflightGuardsForPrepare({
   });
 }
 
+/**
+ * Route the Epic boot cleanup through the shared protected boot-sweep
+ * engine (Story #4373). Reaps merged, done `story-*` branches left over
+ * from prior runs — the protection partition skips any branch with
+ * unpushed work, a dirty worktree, or a still-open parent Story, so an
+ * in-flight Story is never touched. Fast-forward is off: the prepare may
+ * run on the Epic branch, and the fast-forward phase would otherwise
+ * check out the base branch.
+ *
+ * Best-effort — a sweep failure (lock contention, git/gh error) is
+ * swallowed and never blocks or fails the prepare. Skipped in the same
+ * injected-test shape the preflight guards use (a provider injected with
+ * no git seam) so unit tests never spawn real git/gh.
+ */
+async function runBootSweepForPrepare({
+  cwd,
+  config,
+  provider,
+  injectedProvider,
+  injectedGit,
+  injectedSweep,
+  skipPreflightGuards,
+}) {
+  const suppressed =
+    skipPreflightGuards || (Boolean(injectedProvider) && !injectedGit);
+  if (suppressed) return;
+  try {
+    await runBootSweep({
+      cwd,
+      include: ['story-*'],
+      fastForward: false,
+      injectedConfig: config,
+      injectedProvider: provider,
+      injectedSweep,
+      logger: Logger,
+    });
+  } catch (err) {
+    Logger.warn(
+      `[epic-deliver-prepare] ⚠️ boot sweep threw (prepare continues): ${err?.message ?? err}`,
+    );
+  }
+}
+
 /**
  * Resolve the Epic state, preferring the preflight cache (Story #3027) and
  * falling back to a fresh snapshot + wave-DAG pass on miss or baseSha
@@ -333,6 +377,7 @@ export async function runEpicDeliverPrepare({
   steal = false,
   asOperator,
   injectedGit,
+  injectedSweep,
   leaseHeartbeatAt,
   leaseNow,
   skipPreflightGuards = false,
@@ -365,6 +410,16 @@ export async function runEpicDeliverPrepare({
     skipPreflightGuards,
   });
 
+  await runBootSweepForPrepare({
+    cwd,
+    config,
+    provider,
+    injectedProvider,
+    injectedGit,
+    injectedSweep,
+    skipPreflightGuards,
+  });
+
   const { state, cacheStatus } = await resolvePrepareState({
     epicId,
     cwd,

package/.agents/scripts/git-cleanup.js

@@ -55,11 +55,14 @@ import {
   computeProtectedSet,
 } from './lib/orchestration/git-cleanup/phases/filters.js';
 import {
+  branchLastCommitAt,
   branchTipSha,
   classifyLatestPr,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
 } from './lib/orchestration/git-cleanup/phases/git-probes.js';
 import { parseCleanupArgs } from './lib/orchestration/git-cleanup/phases/parse-args.js';
 import {
@@ -74,6 +77,7 @@ import {
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
 } from './lib/orchestration/git-cleanup/phases/render.js';
 import {
@@ -86,6 +90,7 @@ import {
 
 // Public surface preserved for tests + `single-story-sweep.js`.
 export {
+  branchLastCommitAt,
   branchTipSha,
   buildAllowlistDecider,
   buildGlobFilter,
@@ -105,13 +110,16 @@ export {
   planFastForward,
   planStashes,
   probeAllPrs,
+  probeContentEquivalent,
   probeLatestPr,
   probeMergedPr,
+  refExists,
   renderDeferredLine,
   renderDryRun,
   renderExecutionLine,
   renderExecutionSummary,
   renderLatestPrSkipLine,
+  renderNotMergedSkipLine,
   renderPruneLine,
   stashRefIndex,
 };

package/.agents/scripts/lib/checks/subagent-agent-tool-required.js

@@ -1,30 +1,44 @@
 /**
- * subagent-agent-tool-required — refuse-and-print check.
+ * subagent-agent-tool-required — supported-depth guard (refuse-and-print).
  *
- * Detects sub-agent workflow definitions that declare access to the
- * `Agent` tool (or otherwise document nested Agent dispatch). Nested
- * Agent dispatch is not supported in this Claude Code, so any
- * wave-runner-as-sub-agent or cascading fan-out design that declares
- * `Agent` in its tool list will silently fail at runtime. The remediation
- * is to flatten the fan-out back to the host agent and run sub-agents at
- * one level only.
+ * Nested `Agent` dispatch from a sub-agent is **supported** on this Claude
+ * Code build (verified depth 2, announced max depth 5 — Claude Code
+ * 2.1.202, re-spiked 2026-07-08; see Epic #4385 / watch #2870). A level-1
+ * sub-agent carries `Agent` in its primary toolset and can spawn a working
+ * level-2 sub-agent. Declaring `Agent` in a sub-agent workflow is therefore
+ * a legitimate design choice, **not** an automatic runtime failure.
+ *
+ * What this check guards is the one case that still fails: a fan-out whose
+ * declared nesting depth exceeds the announced/supported ceiling. A dispatch
+ * chain deeper than the harness supports will silently fail at runtime, so a
+ * workflow that declares `Agent` together with a `nesting-depth` beyond the
+ * ceiling is flagged as a blocker. A sub-agent that declares `Agent` at a
+ * supported depth (the common case — an undeclared depth is treated as the
+ * shallow level-1 fan-out) produces no finding.
+ *
+ * This inverts the historical guard (Story #4387): the check used to refuse
+ * `Agent` in *any* sub-agent workflow on the now-false rationale that
+ * sub-agents cannot dispatch. It no longer strips a real capability; it only
+ * catches an over-deep fan-out. The self-healing surface is preserved — it is
+ * re-scoped, not removed.
  *
  * Scope: 'epic-deliver', 'retro'. Surfaces as a blocker at preflight for
  * `epic-deliver` (the fan-out site) and as audit signal at retro.
  *
- * The check is `refuse-and-print` — auto-rewriting a workflow's tool
- * list would silently change runtime behavior in ways the operator may
- * not have intended (the workflow's logic may depend on the missing
- * tool). The fixCommand cites the flatten-fan-out remediation pattern.
+ * The check is `refuse-and-print` — auto-rewriting a workflow's declared
+ * depth or tool list would silently change runtime behavior in ways the
+ * operator may not have intended. The fixCommand explains how to bring the
+ * fan-out back under the ceiling (reduce the declared depth or split the
+ * deepest level out), and is explicit that stripping `Agent` is NOT the fix.
  *
- * Implementation note: we scan `.agents/workflows/*.md` for workflow
- * files whose frontmatter or body identifies them as a sub-agent role
- * AND whose `tools:` declaration includes `Agent`. The marker for
- * "sub-agent" is the phrase `sub-agent` appearing in the description /
- * overview region. This keeps the check stable while the workflow
- * surface evolves — the project doesn't yet have a structured
- * `role: sub-agent` frontmatter field, and the textual marker is what
- * the human contributors actually grep for.
+ * Implementation note: we scan `.agents/workflows/*.md` for workflow files
+ * whose frontmatter or body identifies them as a sub-agent role AND whose
+ * `tools:` declaration includes `Agent`, then read the workflow's declared
+ * `nesting-depth`. The marker for "sub-agent" is the phrase `sub-agent`
+ * appearing in the description / overview region. The depth is read from a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` body marker; an absent declaration is treated
+ * as depth 1 (a single, shallow fan-out level).
  */
 
 import { readdirSync, readFileSync } from 'node:fs';
@@ -32,6 +46,17 @@ import path from 'node:path';
 
 const WORKFLOWS_DIR_DEFAULT = path.join('.agents', 'workflows');
 
+/**
+ * Announced maximum nesting depth the Claude Code harness supports for
+ * sub-agent fan-out. Depth 2 is independently verified; depths 3–5 are
+ * announced but not yet re-spiked (Epic #4385 / watch #2870). A workflow
+ * declaring a fan-out deeper than this ceiling is flagged. Operators can pin
+ * a stricter (or, once verified, looser) ceiling via `state.supportedDepth`.
+ *
+ * @type {number}
+ */
+export const ANNOUNCED_MAX_DEPTH = 5;
+
 /**
  * Walk a workflow directory and return absolute `.md` file paths
  * (non-recursive — the workflows surface is one level deep; helpers/
@@ -127,17 +152,57 @@ function findAgentToolDeclaration(parts) {
   return null;
 }
 
+/**
+ * Parse the workflow's declared nesting depth. A sub-agent that declares
+ * `Agent` may also declare how deep its fan-out reaches via a
+ * `nesting-depth:` (or `agent-depth:`) frontmatter field, or a
+ * `<!-- nesting-depth: N -->` marker in the body. Returns the integer
+ * depth, or `null` when no depth is declared (the caller treats an absent
+ * declaration as the shallow level-1 fan-out).
+ *
+ * @param {{ frontmatter: string, body: string }} parts
+ * @returns {number | null}
+ */
+function parseDeclaredDepth(parts) {
+  const { frontmatter, body } = parts;
+  const fmMatch = frontmatter.match(
+    /^[ \t]*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*$/m,
+  );
+  if (fmMatch) return Number.parseInt(fmMatch[1], 10);
+  const bodyMatch = body.match(
+    /<!--\s*(?:nesting-depth|agent-depth)\s*:\s*(\d+)\s*-->/,
+  );
+  if (bodyMatch) return Number.parseInt(bodyMatch[1], 10);
+  return null;
+}
+
+/**
+ * Resolve the supported depth ceiling for a detect run. Operators may pin a
+ * stricter (or, once verified, looser) ceiling via `state.supportedDepth`;
+ * an unset or non-positive-integer override falls back to the announced max.
+ *
+ * @param {{ supportedDepth?: unknown } | null | undefined} state
+ * @returns {number}
+ */
+function resolveCeiling(state) {
+  const override = state?.supportedDepth;
+  if (Number.isInteger(override) && override > 0) return override;
+  return ANNOUNCED_MAX_DEPTH;
+}
+
 const FIX_COMMAND = [
-  '# Flatten fan-out to the host. Sub-agents cannot dispatch other agents.',
-  "# Remove the `Agent` entry from this workflow's `tools:` declaration,",
-  '# move any fan-out logic up to the parent / host invocation, and have',
-  '# the parent dispatch the leaf sub-agents directly.',
+  '# Nested Agent dispatch IS supported (verified depth 2, announced max 5 —',
+  '# Claude Code 2.1.202). This workflow declares a fan-out deeper than the',
+  '# supported ceiling, so the deepest dispatch chain will fail at runtime.',
   '#',
-  '# Pattern (host workflow):',
-  '#   for each child: Agent(prompt=<child workflow>, args=<id>)',
+  '# Bring the fan-out back under the ceiling — either:',
+  '#   1. Lower the declared `nesting-depth` to <= the supported ceiling, or',
+  '#   2. Split the deepest level out to a shallower sibling fan-out so no',
+  '#      single dispatch chain exceeds the supported depth.',
   '#',
-  '# Pattern (sub-agent workflow):',
-  '#   tools: [Bash, Read, Edit, Grep, Glob, Write]   # NO Agent',
+  '# Do NOT strip `Agent` from the tool list to silence this. Sub-agents CAN',
+  '# dispatch nested agents at a supported depth; removing the tool would',
+  '# disable a legitimate capability, not fix the depth overflow.',
 ].join('\n');
 
 export default {
@@ -149,6 +214,7 @@ export default {
   detect(state) {
     const cwd = state?.cwd ?? process.cwd();
     const root = state?.scanRoot ?? path.join(cwd, WORKFLOWS_DIR_DEFAULT);
+    const ceiling = resolveCeiling(state);
     const files = listWorkflowFiles(root);
     const offences = [];
     for (const file of files) {
@@ -162,18 +228,29 @@ export default {
       const parts = splitFrontmatter(src);
       const where = findAgentToolDeclaration(parts);
       if (!where) continue;
+      // Declaring `Agent` is legitimate. Only a fan-out deeper than the
+      // supported ceiling is a runtime hazard; an undeclared depth is the
+      // shallow level-1 fan-out and always within the ceiling.
+      const depth = parseDeclaredDepth(parts) ?? 1;
+      if (depth <= ceiling) continue;
       offences.push({
         file: path.relative(root, file).replace(/\\/g, '/'),
         where,
+        depth,
       });
     }
     if (offences.length === 0) return null;
-    const detail = offences.map((o) => `${o.file} — ${o.where}`).join('\n');
+    const detail = offences
+      .map(
+        (o) =>
+          `${o.file} — declares Agent at nesting-depth ${o.depth} (exceeds supported ceiling ${ceiling}); ${o.where}`,
+      )
+      .join('\n');
     return {
       id: 'subagent-agent-tool-required',
       severity: 'blocker',
       scope: state?.scope ?? 'epic-deliver',
-      summary: `${offences.length} sub-agent workflow(s) declare Agent in their tool list — nested Agent dispatch is unsupported`,
+      summary: `${offences.length} sub-agent workflow(s) declare an Agent fan-out deeper than the supported nesting ceiling (${ceiling})`,
       detail,
       fixCommand: FIX_COMMAND,
       autoCorrectable: false,

package/.agents/scripts/lib/epic-plan-ideation.js

@@ -13,6 +13,10 @@
  * mock the provider call without touching the GitHub HTTP client.
  */
 
+import {
+  extractFrameworkStamp,
+  stampFrameworkVersion,
+} from './framework-version.js';
 import { TYPE_LABELS } from './label-constants.js';
 
 // Canonical section keys match the rendered template at
@@ -113,24 +117,33 @@ export function parseOnePager(onePager) {
  * sections are rendered as `_(not specified)_` so the operator can spot
  * gaps during the HITL review (Phase 3).
  *
+ * Story #4382 — the rendered body is stamped with the Mandrel framework
+ * version + authoring date (hidden `mandrel_version` / `authored_at` meta
+ * field + a visible `> 🏷️ Authored with Mandrel …` marker) via
+ * {@link stampFrameworkVersion}. Pass `stamp` to preserve a
+ * previously-authored version on re-render (the Epic edit path does this);
+ * omit it to stamp the running version and today's date.
+ *
  * @param {{
  *   onePager: string,
  *   template: string,
+ *   stamp?: { version?: string, authoredAt?: string },
  * }} args
  * @returns {{ title: string, body: string }}
  */
-export function renderEpicBody({ onePager, template }) {
+export function renderEpicBody({ onePager, template, stamp }) {
   if (!template || typeof template !== 'string') {
     throw new Error('renderEpicBody: template must be a non-empty string');
   }
   const parsed = parseOnePager(onePager);
 
-  const body = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+  const rendered = template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
     if (key === 'title') return parsed.title;
     const value = parsed[key];
     return value && value.length > 0 ? value : '_(not specified)_';
   });
 
+  const body = stampFrameworkVersion(rendered, stamp ?? {});
   return { title: parsed.title, body };
 }
 
@@ -226,7 +239,15 @@ export async function updateEpicFromOnePager({
     );
   }
 
-  const { title, body } = renderEpicBody({ onePager, template });
+  // Story #4382 — preserve the originally-authored version stamp on edit
+  // rather than bumping it to whatever version is running now. When the
+  // current body carries no stamp (legacy Epic), a fresh stamp is applied.
+  const priorStamp = extractFrameworkStamp(currentBody ?? '');
+  const stamp = priorStamp
+    ? { version: priorStamp.version, authoredAt: priorStamp.authoredAt }
+    : undefined;
+
+  const { title, body } = renderEpicBody({ onePager, template, stamp });
 
   if (typeof currentBody === 'string' && currentBody === body) {
     return { epicId, title, body, changed: false };