mandrel 1.63.0 → 1.64.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -277,7 +277,7 @@ export function ensureDependenciesInstalled(ctx) {
   });
   if (result.status !== 0) {
     throw new Error(
-      `[bootstrap] ${manager} install failed (exit ${result.status}). Resolve the install error and re-run.`,
+      `[Bootstrap] ${manager} install failed (exit ${result.status}). Resolve the install error and re-run.`,
     );
   }
   return { ran: true, manager, skipped: false };
@@ -462,7 +462,7 @@ export function runSyncCommands(ctx) {
   });
   if (result.status !== 0) {
     throw new Error(
-      `[bootstrap] sync-claude-commands.js failed (exit ${result.status}): ${(
+      `[Bootstrap] sync-claude-commands.js failed (exit ${result.status}): ${(
         result.stderr ?? ''
       )
         .trim()
@@ -615,12 +615,12 @@ export function checkWindowsGitPerf(ctx) {
 const fatalNodeCheck = (result) =>
   result.ok
     ? null
-    : `[bootstrap] Node ${result.version} is below required ${result.required}. Upgrade Node and re-run.`;
+    : `[Bootstrap] Node ${result.version} is below required ${result.required}. Upgrade Node and re-run.`;
 
 const fatalValidation = (result) =>
   result.ok
     ? null
-    : `[bootstrap] .agentrc.json failed schema validation: ${JSON.stringify(
+    : `[Bootstrap] .agentrc.json failed schema validation: ${JSON.stringify(
         result.errors,
         null,
         2,
@@ -629,7 +629,7 @@ const fatalValidation = (result) =>
 const fatalParity = (result) =>
   result.ok
     ? null
-    : `[bootstrap] Parity check failed — workflows missing commands: ${
+    : `[Bootstrap] Parity check failed — workflows missing commands: ${
         result.missingCommand.join(', ') || '(none)'
       }; orphan commands: ${result.orphanCommand.join(', ') || '(none)'}`;
 

package/.agents/scripts/lib/bootstrap/prompt.js

@@ -286,7 +286,11 @@ export async function resolveFromPicker(ctx) {
 
   const normalized = choices.map(normalizePickerChoice);
   const rl = await ctx.getRl();
-  ctx.output.write(`${ctx.q.message}:\n`);
+  // The picker header uses `pickerMessage` when set, so a question can show
+  // list-oriented guidance here (e.g. "Select existing or press ENTER to create
+  // new one") while the manual-entry fall-through prompt (`askOnce`) uses the
+  // shorter `message` (e.g. "New GitHub repo name"). Falls back to `message`.
+  ctx.output.write(`${ctx.q.pickerMessage ?? ctx.q.message}:\n`);
   normalized.forEach((choice, index) => {
     ctx.output.write(`  ${index + 1}) ${choice.label}\n`);
   });

package/.agents/scripts/lib/detect-package-manager.js

@@ -1,11 +1,11 @@
 /**
  * detect-package-manager — shared lockfile-probe helper (Story #4048 B3).
  *
- * Five independent copies of this lockfile probe existed across the codebase:
+ * Several independent copies of this lockfile probe existed across the
+ * codebase before this consolidation:
  *   - `lib/cli/update.js#detectPackageManager`
  *   - `lib/bootstrap/project-bootstrap.js#detectPackageManager`
  *   - `lib/runtime-deps/preflight.js#detectPackageManager`
- *   - `lib/onboard/detect-stack.js#detectPackageManager`
  *   - `lib/worktree/node-modules-strategy.js#selectInstallCommand` (inline)
  *
  * This module is the single authoritative implementation. It uses the

package/.agents/scripts/lib/onboard/init-tail.js

@@ -2,18 +2,17 @@
  * init-tail.js — post-bootstrap onboarding tail for `mandrel init`.
  *
  * Called by `mandrel init` after `bootstrap.js` completes successfully on
- * the "configure now" path. Sequences the four phases that walk an operator
+ * the "configure now" path. Sequences the three phases that walk an operator
  * from a freshly bootstrapped project to a ready-to-plan workspace:
  *
- *   Phase 1 — Detect the consumer stack (lib/onboard/detect-stack.js).
- *   Phase 2 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
- *   Phase 3 — Run `mandrel doctor` as a readiness gate.
- *   Phase 4 — Print the /plan handoff next-step text.
+ *   Phase 1 — Offer to scaffold missing docsContextFiles (scaffold-docs.js).
+ *   Phase 2 — Run `mandrel doctor` as a readiness gate.
+ *   Phase 3 — Print the /plan handoff next-step text.
  *
  * The whole tail is idempotent: re-running after an already-onboarded project
- * re-detects, re-checks, and re-offers scaffolding without duplicating stubs
- * (the scaffolder only writes genuinely absent files) and without modifying
- * anything (doctor is read-only).
+ * re-checks and re-offers scaffolding without duplicating stubs (the scaffolder
+ * only writes genuinely absent files) and without modifying anything (doctor is
+ * read-only).
  *
  * Injectable seams: `runDoctor`, `stdout`, `confirmScaffold`, and `isTTY`
  * allow the unit suite to drive every branch without real I/O.
@@ -22,10 +21,9 @@
  */
 
 import { spawnSync as defaultSpawnSync } from 'node:child_process';
-import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
 
-import { detectStack } from './detect-stack.js';
 import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
 
 // ---------------------------------------------------------------------------
@@ -38,7 +36,7 @@ import { STUB_MARKER, scaffoldDocs } from './scaffold-docs.js';
  * @type {string}
  */
 export const PLAN_HANDOFF_TEXT =
-  '\n✅  Mandrel is ready. Start your first Epic:\n\n' +
+  '\n✅  Mandrel is ready. Start your first project:\n\n' +
   '    /plan --idea "<one-line description of what you want to build>"\n\n' +
   'Or, if you already have a `type::epic` Issue open:\n\n' +
   '    /plan <epicId>\n';
@@ -47,24 +45,6 @@ export const PLAN_HANDOFF_TEXT =
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-/**
- * Format a stack-detection result as a human-readable report line.
- *
- * @param {{ packageManager: string|null, testRunner: string|null, primaryLanguage: string|null }} stack
- * @returns {string}
- */
-function formatStackReport(stack) {
-  const pm = stack.packageManager ?? '(unknown)';
-  const runner = stack.testRunner ?? '(unknown)';
-  const lang = stack.primaryLanguage ?? '(unknown)';
-  return (
-    '\n[init] Stack detection:\n' +
-    `  Package manager : ${pm}\n` +
-    `  Test runner     : ${runner}\n` +
-    `  Primary language: ${lang}\n`
-  );
-}
-
 /**
  * Format a list of missing docs as a human-readable report (no prompt).
  *
@@ -75,30 +55,54 @@ function formatMissingList(missing) {
   if (missing.length === 0) return '';
   const list = missing.map((f) => `  • ${f}`).join('\n');
   return (
-    '\n[init] The following docsContextFiles are missing — agents load\n' +
-    'these before every task:\n' +
+    '\n[Final Checks] The following docsContextFiles are missing,\n' +
+    'agents will load degraded context until you create them:\n' +
     `${list}\n`
   );
 }
 
 /** Prompt text shown only on a TTY when asking to scaffold. */
-const SCAFFOLD_PROMPT = '\nScaffold stubs now? [y/N]: ';
+const SCAFFOLD_PROMPT = '\nCreate placeholders? [Y/n]: ';
 
 /**
- * Synchronous y/N read from stdin (fd 0). Returns `false` on any read error
- * or when the user enters something other than `y` / `yes`.
+ * Async y/N read from stdin via `node:readline` (mirrors the prompt mechanism
+ * in `bootstrap.js`). Returns on Enter and never blocks waiting for EOF the way
+ * `fs.readFileSync(0)` did — that EOF-blocking read hung `mandrel init` on an
+ * interactive TTY. Yes is the default (`[Y/n]`): a bare Enter — or anything but
+ * an explicit `n`/`no` — resolves to `true` (create the placeholders), since the
+ * missing docs are known-needed and the stubs carry a `MANDREL:STUB` marker the
+ * `/plan` preflight still flags until they are fleshed out. A read error
+ * resolves to `false` so a genuine I/O failure never writes unattended. The
+ * prompt text is written by the caller via `stdout`, so the question string
+ * passed here is empty.
+ *
+ * `terminal: false` is **load-bearing**: with terminal mode on (the default
+ * when stdout is a TTY) readline emits cursor-control escapes
+ * (`\x1b[1G\x1b[0J`) that erase the `Create placeholders? [Y/n]:` prompt already
+ * written via the caller's `stdout`, leaving the operator staring at a blank,
+ * dead-looking line. Disabling terminal mode preserves the pre-written prompt
+ * and reads the line via the TTY's cooked-mode echo. `createInterface` is
+ * injectable so a test can assert this option is set (regression guard).
  *
- * @returns {boolean}
+ * @param {{ createInterface?: typeof readline.createInterface }} [opts]
+ * @returns {Promise<boolean>}
  */
-function syncConfirm() {
-  let answer = '';
+export async function readConfirm({
+  createInterface = readline.createInterface,
+} = {}) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
   try {
-    const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+    const answer = (await rl.question('')).trim().toLowerCase();
+    return answer !== 'n' && answer !== 'no';
   } catch {
-    answer = '';
+    return false;
+  } finally {
+    rl.close();
   }
-  return answer === 'y' || answer === 'yes';
 }
 
 // ---------------------------------------------------------------------------
@@ -119,14 +123,13 @@ function syncConfirm() {
  *   - Run `mandrel doctor`; injectable for tests.
  * @param {boolean} [opts.isTTY] - Whether stdin is a TTY (defaults to
  *   `Boolean(process.stdin.isTTY)`).
- * @returns {{
- *   stack: { packageManager: string|null, testRunner: string|null, primaryLanguage: string|null },
+ * @returns {Promise<{
  *   scaffoldResult: object,
  *   doctorStatus: number,
  *   ok: boolean,
- * }}
+ * }>}
  */
-export function runInitTail({
+export async function runInitTail({
   root,
   stdout = (s) => process.stdout.write(s),
   confirmScaffold,
@@ -140,7 +143,7 @@ export function runInitTail({
   // it. When using the default, auto-decline on non-TTY so the scaffolder
   // never writes unattended.
   const usingDefaultConfirm = confirmScaffold == null;
-  const confirmFn = confirmScaffold ?? (() => syncConfirm());
+  const confirmFn = confirmScaffold ?? readConfirm;
 
   // Default doctor runner — spawns `mandrel doctor` via the locally installed
   // bin; inherits stdio so the report streams to the terminal.
@@ -159,21 +162,12 @@ export function runInitTail({
 
   const doctorFn = runDoctor ?? defaultRunDoctor;
 
-  // --- Phase 1: Detect the stack -------------------------------------------
-  let stack;
-  try {
-    stack = detectStack(projectRoot);
-  } catch {
-    stack = { packageManager: null, testRunner: null, primaryLanguage: null };
-  }
-  stdout(formatStackReport(stack));
-
-  // --- Phase 2: Offer to scaffold missing docsContextFiles -----------------
+  // --- Phase 1: Offer to scaffold missing docsContextFiles -----------------
   const preview = scaffoldDocs({ root: projectRoot, write: false });
   let scaffoldResult = preview;
 
   if (preview.missing.length === 0) {
-    stdout('\n[init] All docsContextFiles are present.\n');
+    stdout('\n[Final Checks] All docsContextFiles are present.\n');
   } else {
     stdout(formatMissingList(preview.missing));
     // On non-TTY without an injected confirm, auto-decline so the scaffolder
@@ -181,38 +175,35 @@ export function runInitTail({
     // the prompt and consult the confirm function.
     const canPrompt = tty || !usingDefaultConfirm;
     if (canPrompt) stdout(SCAFFOLD_PROMPT);
-    const accepted = canPrompt ? confirmFn() : false;
+    const accepted = canPrompt ? await confirmFn() : false;
     if (accepted) {
       scaffoldResult = scaffoldDocs({ root: projectRoot, write: true });
       if (scaffoldResult.created.length > 0) {
         stdout(
-          `[init] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
+          `[Final Checks] Scaffolded ${scaffoldResult.created.length} stub(s). ` +
             `Each carries a \`${STUB_MARKER}\` marker — replace placeholder ` +
             'content before planning.\n',
         );
       }
     } else {
-      stdout(
-        '[init] Scaffolding declined. docsContextFiles are still missing — ' +
-          'agents will load degraded context until you create them.\n',
-      );
+      stdout('[Final Checks] Placeholders declined.\n');
     }
   }
 
-  // --- Phase 3: Readiness gate (mandrel doctor) ----------------------------
-  stdout('\n[init] Running mandrel doctor…\n');
+  // --- Phase 2: Readiness gate (mandrel doctor) ----------------------------
+  stdout('\n[Final Checks] Final installation summary via mandrel doctor…\n');
   const doctorResult = doctorFn();
   const doctorStatus = doctorResult?.status ?? 1;
 
   if (doctorStatus !== 0) {
     stdout(
-      '\n[init] ❌  Doctor check failed. Resolve the remedies above and\n' +
+      '\n[Final Checks] ❌  Doctor check failed. Resolve the remedies above and\n' +
         'then re-run: mandrel init\n',
     );
-    return { stack, scaffoldResult, doctorStatus, ok: false };
+    return { scaffoldResult, doctorStatus, ok: false };
   }
 
-  // --- Phase 4: Handoff to /plan -------------------------------------------
+  // --- Phase 3: Handoff to /plan -------------------------------------------
   stdout(PLAN_HANDOFF_TEXT);
-  return { stack, scaffoldResult, doctorStatus, ok: true };
+  return { scaffoldResult, doctorStatus, ok: true };
 }

package/.agents/scripts/providers/github/tickets.js

@@ -77,7 +77,7 @@ export function composeStoryBody({
 }) {
   const head = typeof body === 'string' ? body : '';
   const lines = ['---', `parent: #${parentId}`];
-  if (epicId !== undefined && epicId !== null && epicId !== parentId) {
+  if (epicId !== undefined && epicId !== null) {
     lines.push(`Epic: #${epicId}`);
   }
   if (dependencies.length > 0) {

package/.agents/workflows/helpers/deliver-stories.md

@@ -192,7 +192,18 @@ Each Agent call:
 1. Names the Story ID and instructs the child to invoke
    [`helpers/single-story-deliver`](single-story-deliver.md)
    for that Story.
-2. States the **return contract** (see § 2c).
+2. States the **return contract** (see § 2c) and the **no-park rule**: the
+   child MUST drive the close → CI-watch → merge-confirm → `agent::done`
+   sequence to a terminal state *within its own turn* and end **only** by
+   returning the § 2c JSON object. The auto-merge wait is an
+   internally-blocking step (`gh pr checks --watch` blocks the turn), **not**
+   a reason to suspend and hand back. A child that ends its turn with
+   free-form prose and an unconfirmed merge (e.g. "I'll wait for the
+   background watch task…") has violated the contract — the wave loop cannot
+   advance, and the Story strands at `agent::closing` (the Story #1553 /
+   PR #1554 failure mode). There is no "pending" return status: the child
+   returns `done` (merge confirmed), `blocked` (transitioned + friction
+   posted), or `failed`.
 3. Reminds the child of the **non-interactive contract**: no clarifying
    questions — if stuck, transition to `agent::blocked`, post a
    `friction` comment, and exit non-zero.
@@ -209,7 +220,8 @@ Agent call has returned a result (success, blocked, or failed).
 
 ### 2c. Per-Story return contract
 
-Each child returns:
+Each child ends its turn by returning **exactly one** JSON object — never
+free-form prose:
 
 ```json
 {
@@ -223,6 +235,16 @@ Each child returns:
 }
 ```
 
+The status enum is **closed** — `done`, `blocked`, or `failed`. There is no
+"pending" / "waiting" status, because the close-phase auto-merge wait is
+**not** a returnable suspension: the child blocks on `gh pr checks --watch`
+*inside its own turn*, confirms the merge, flips `agent::done`, and only then
+returns `status: "done"`. A child that returns prose instead — parking on the
+CI wait with an unconfirmed merge — breaks the wave loop's ability to advance
+and leaves the Story at `agent::closing` (Story #1553 / PR #1554). The
+single-homed restatement of this no-park rule for the child's own perspective
+is [`single-story-deliver.md` § Step 7](single-story-deliver.md#return-contract).
+
 ### 2d. Wave outcome handling
 
 After every Story in a wave returns:

package/.agents/workflows/helpers/single-story-deliver.md

@@ -336,6 +336,26 @@ coverage rounding, platform-conditional branches, and timing-sensitive
 tests routinely drift between the two. The agent owns the green-CI
 outcome, not just the push.
 
+> **The auto-merge wait is an internally-blocking step, not a reason to end
+> your turn.** This is the single most important contract of this workflow,
+> and the seam where a worker most often misbehaves: it delivers up to arming
+> auto-merge, then ends its turn with **free-form prose** — e.g. "I'll wait
+> for the background watch task to complete" or "the next event will be its
+> completion notification" — leaving the merge unconfirmed and the Story
+> stranded at `agent::closing` (observed on Story #1553 / PR #1554). **Do not
+> do this.** `gh pr checks <prNumber> --watch` *blocks the current turn* until
+> CI resolves — that is the mechanism by which you wait. You MUST keep your
+> turn alive across the wait: watch → (fix + push + re-watch on red) → confirm
+> the merge (Step 5) → flip `agent::done` → run the post-merge steps → and
+> only then return the terminal JSON status contract (Step 4 of
+> [`deliver-stories.md` § 2c](deliver-stories.md), mirrored in
+> [§ Return contract](#return-contract) for the standalone caller). The CI
+> wait NEVER terminates your turn; **only** a confirmed-`MERGED` PR (→
+> `status: "done"`), an `agent::blocked` transition (→ `status: "blocked"`),
+> or an unrecoverable failure (→ `status: "failed"`) does. Ending your turn
+> with prose and an unconfirmed merge is a contract violation — it is the very
+> bug this workflow exists to prevent.
+
 After `single-story-close.js` succeeds, enter the watch + fix loop:
 
 ```bash
@@ -348,7 +368,9 @@ When the watch exits:
   still at `agent::closing` with its issue OPEN at this point (Step 3
   deferred the `agent::done` flip). The `Closes #<id>` footer closes the
   Story issue when the merge lands; Step 5 confirms the merge and Step 5.5
-  flips the Story to `agent::done`. Proceed to Step 5.
+  flips the Story to `agent::done`. **Proceed to Step 5 within the same
+  turn** — do not end your turn here. Green CI is the *start* of the
+  merge-confirm sequence, not a terminal state (see Step 7's no-park rule).
 - **Any check ✗** — diagnose, fix, and push a new commit on
   `story-<storyId>`, then re-watch. Auto-merge stays enabled across
   retries; no need to re-arm it. The Story stays at `agent::closing`
@@ -582,6 +604,67 @@ cleanup.
 
 ---
 
+## Step 7 — Return contract (**required when dispatched as a sub-agent**) {#return-contract}
+
+When this workflow runs as a per-Story sub-agent (dispatched by `/deliver`
+via [`deliver-stories.md` § 2a/2c](deliver-stories.md)), the **only**
+acceptable way to end your turn is to **return a single terminal JSON status
+object** — never free-form prose:
+
+```json
+{
+  "storyId": <number>,
+  "status": "done" | "blocked" | "failed",
+  "phase": "init|implementing|closing|blocked|done",
+  "branchDeleted": <boolean>,
+  "blockerCommentId": <string|null>,
+  "detail": "<one-liner: what changed + what was verified, e.g. PR #N merged>",
+  "renderedBody": "<terminal Story body>"
+}
+```
+
+This is the same envelope [`deliver-stories.md` § 2c](deliver-stories.md)
+mandates; this section is its single-homed restatement for the standalone
+worker so the contract is self-contained when this workflow is the entry
+point.
+
+**The auto-merge wait does not produce a fourth status.** There is no
+"pending" or "waiting" terminal — the CI/auto-merge wait is handled
+*internally* by blocking on `gh pr checks --watch` (Step 4) and confirming
+the merge (Step 5). You return **only** when you have reached a genuinely
+terminal state:
+
+- **`status: "done"`** — the PR is confirmed `state: "MERGED"` (Step 5),
+  the Story carries `agent::done`, and Steps 5.5 / 6 have run. `phase: "done"`,
+  `branchDeleted: true`.
+- **`status: "blocked"`** — you transitioned the Story to `agent::blocked`
+  and posted a `friction` comment (acceptance self-eval block in Step 1a, a
+  base-sync conflict, or an operator-blocking CI failure / Anti-Thrashing
+  stop in Step 4). `phase: "blocked"`, `blockerCommentId` set.
+- **`status: "failed"`** — an unrecoverable failure outside the blocked
+  protocol. `phase` reflects where it died.
+
+A turn that ends with prose ("I'll wait for the watch task…", "the next event
+will be its completion notification…") and an **unconfirmed merge** is a
+**contract violation** (the Story #1553 / PR #1554 failure mode): the parent
+wave loop cannot distinguish "still working" from "done but silent", and the
+Story strands at `agent::closing`. If you genuinely cannot confirm the merge,
+that is a `blocked` or `failed` outcome with the JSON contract above — not a
+prose hand-off.
+
+> **Handoff discipline — report state, not process.** Populate the envelope
+> with essential terminal state only (mirroring the fields
+> `single-story-close.js` / `story-phase.js` already emit). Do not narrate the
+> steps you took, and do not prescribe how the next stage should work. Prose
+> process commentary only bloats the hydrated prompt
+> (`delivery.maxTokenBudget` elision). When run **interactively** (no parent
+> aggregator), this JSON envelope is optional — relay terminal state to the
+> operator in prose instead — but the **no-park rule still holds**: never end
+> an interactive turn with an unconfirmed merge either; block on the watch,
+> confirm, and report the merged outcome.
+
+---
+
 ## Idempotence
 
 - `single-story-init.js` re-prints the same `workCwd` without recreating

package/docs/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.63.0...mandrel-v1.64.0) (2026-06-14)
+
+
+### Added
+
+* **bootstrap:** polish init/bootstrap preflight + UX copy, drop unused stack detection ([#4113](https://github.com/dsj1984/mandrel/issues/4113)) ([c775418](https://github.com/dsj1984/mandrel/commit/c77541846508047f1101158e67ac2a59c8577101))
+* **cli:** mandrel init banner + Welcome prompt, sync 'Installed' wording ([#4109](https://github.com/dsj1984/mandrel/issues/4109)) ([c516d39](https://github.com/dsj1984/mandrel/commit/c516d3903080c5e6838e833dbddf20ab0d4af1cd))
+
+
+### Fixed
+
+* 2-tier Stories un-initializable: composeStoryBody omits `Epic: #N` when epicId === parentId, blocking the /deliver wave loop ([#4102](https://github.com/dsj1984/mandrel/issues/4102)) ([#4103](https://github.com/dsj1984/mandrel/issues/4103)) ([2431cf6](https://github.com/dsj1984/mandrel/commit/2431cf6e7330b9cf98a7f54b60ba8d3df46f635c))
+* **init:** set terminal:false on readline confirms so the prompt is not erased (refs [#4106](https://github.com/dsj1984/mandrel/issues/4106)) ([#4108](https://github.com/dsj1984/mandrel/issues/4108)) ([e31e767](https://github.com/dsj1984/mandrel/commit/e31e767a6d69519faf120bf08ce55d0272a46416))
+* **init:** use node:readline for confirm prompts so init does not hang (refs [#4106](https://github.com/dsj1984/mandrel/issues/4106)) ([#4107](https://github.com/dsj1984/mandrel/issues/4107)) ([2b56d08](https://github.com/dsj1984/mandrel/commit/2b56d0851f403fd97c86e6097fd9d62446ee2257))
+
 ## [1.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.62.0...mandrel-v1.63.0) (2026-06-13)
 
 

package/lib/cli/init.js

@@ -50,9 +50,10 @@
  *                  for `./.agents/` in the cwd
  *   - `runStep`  — `(cmd, args) => { status }`; runs one install/sync/bootstrap
  *                  step. Defaults to a `spawnSync` runner with `stdio: inherit`.
- *   - `confirm`  — `() => boolean`; reads the operator's yes/no answer (true =
- *                  configure now). Defaults to a synchronous stdin readline
- *                  prompt with yes as the default.
+ *   - `confirm`  — `() => boolean | Promise<boolean>`; reads the operator's
+ *                  yes/no answer (true = configure now). Defaults to a
+ *                  `node:readline` stdin prompt (awaited) with yes as the
+ *                  default.
  *   - `stdout`   — `(s) => void`; defaults to `process.stdout.write`.
  *   - `isTTY`    — boolean; defaults to `process.stdin.isTTY`.
  *   - `exit`     — `(code) => void`; defaults to `process.exit`.
@@ -66,6 +67,7 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import readline from 'node:readline/promises';
 import { pathToFileURL } from 'node:url';
 
 // Lazily resolved at runtime so cold-start `npx mandrel init` (where
@@ -119,11 +121,29 @@ const BOOTSTRAP_SCRIPT = path.join('.agents', 'scripts', 'bootstrap.js');
 const SYNC_BIN = path.join('node_modules', PACKAGE_NAME, 'bin', 'mandrel.js');
 
 const PROMPT_TEXT =
-  'The Mandrel .agents package has been copied to your directory.\n' +
-  'Would you like to begin the interactive process to setup your local and ' +
-  'github environments now? [Y/n]: ';
+  '\n' +
+  'Welcome to Mandrel!\n\n' +
+  'Check .agents/README.md for more quick start instructions, flag options, and documentation.\n\n' +
+  'Begin interactive setup? [Y/n]: ';
 
-const FILES_ONLY_HINT = 'Configure any time with: npx mandrel init\n';
+const FILES_ONLY_HINT = 'Setup any time with: npx mandrel init\n';
+
+// ASCII banner printed once at the very top of `mandrel init`, before any
+// install/sync output streams to the terminal. Paste multi-line ASCII art
+// between the fences below. `String.raw` keeps backslashes literal so the art
+// renders exactly as pasted — the only characters to avoid inside are a
+// literal backtick and the `${` sequence. The leading/trailing blank lines
+// frame the art in the terminal.
+const BANNER = String.raw`
+
+   ______  ___             _________           ______
+   ___   |/  /_____ _____________  /______________  /
+   __  /|_/ /_  __ '/_  __ \  __  /__  ___/  _ \_  /
+   _  /  / / / /_/ /_  / / / /_/ / _  /   /  __/  /
+   /_/  /_/  \__,_/ /_/ /_/\__,_/  /_/    \___//_/
+____________________________________________________
+
+`;
 
 // On win32, `npm` resolves to a `.cmd` shim that Node refuses to spawn without
 // a shell after the CVE-2024-27980 hardening; mirror update.js and set
@@ -175,7 +195,7 @@ function buildBootstrapArgs(argv, assumeYes) {
  *   argv?: string[],
  *   exists?: (relPath: string) => boolean,
  *   runStep?: (cmd: string, args: string[]) => { status: number | null },
- *   confirm?: () => boolean,
+ *   confirm?: () => boolean | Promise<boolean>,
  *   stdout?: (s: string) => void,
  *   isTTY?: boolean,
  *   afterBootstrap?: (root: string) => Promise<{ ok?: boolean } | void> | { ok?: boolean } | void,
@@ -260,7 +280,7 @@ export async function planInit({
     proceed = false;
   } else {
     stdout(PROMPT_TEXT);
-    proceed = confirm();
+    proceed = await confirm();
   }
 
   if (proceed) {
@@ -338,23 +358,44 @@ function defaultRunStep(cmd, args) {
 }
 
 /**
- * Default `confirm` seam — synchronous yes/no prompt. Reads one line from stdin
- * and normalizes it to a boolean; any input other than an explicit "no"
- * (`n`/`no`, case-insensitive) — including bare Enter — defaults to `true`
- * (configure), matching the `[Y/n]` convention where yes is the default.
+ * Default `confirm` seam — yes/no prompt read via `node:readline` (mirrors the
+ * prompt mechanism in `bootstrap.js`). Returns on Enter and never blocks
+ * waiting for EOF the way `fs.readFileSync(0)` did — that EOF-blocking read hung
+ * `mandrel init` on an interactive TTY. Any input other than an explicit "no"
+ * (`n`/`no`, case-insensitive) — including bare Enter — resolves to `true`
+ * (configure), matching the `[Y/n]` convention where yes is the default. The
+ * prompt text is written by `planInit` via `stdout`, so the question string
+ * passed here is empty.
  *
- * @returns {boolean}
+ * `terminal: false` is **load-bearing**, not cosmetic: with terminal mode on
+ * (the default when stdout is a TTY) readline emits cursor-control escapes
+ * (`\x1b[1G\x1b[0J` — column-1 + erase-to-end-of-screen) when it takes over the
+ * line, which **erases the `[Y/n]:` prompt already written via `stdout`** — the
+ * operator then sees only the first prompt line and a dead-looking cursor.
+ * Disabling terminal mode leaves the pre-written prompt intact and reads the
+ * line via the TTY's own cooked-mode echo. `createInterface` is injectable so a
+ * test can assert this option is set (regression guard).
+ *
+ * @param {{ createInterface?: typeof readline.createInterface }} [opts]
+ * @returns {Promise<boolean>}
  */
-function defaultConfirm() {
-  let answer = '';
+export async function defaultConfirm({
+  createInterface = readline.createInterface,
+} = {}) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: false,
+  });
   try {
-    const buf = fs.readFileSync(0, 'utf8');
-    answer = buf.split('\n', 1)[0].trim().toLowerCase();
+    const answer = (await rl.question('')).trim().toLowerCase();
+    return answer !== 'n' && answer !== 'no';
   } catch {
-    // No readable line (e.g. stdin closed) → fall through to the default.
-    answer = '';
+    // No readable line (e.g. stdin closed) → default to yes (configure).
+    return true;
+  } finally {
+    rl.close();
   }
-  return answer !== 'n' && answer !== 'no';
 }
 
 /**
@@ -376,6 +417,10 @@ export default async function run(argv = []) {
     return;
   }
 
+  // Banner is the very first output — before the install + sync steps that
+  // planInit kicks off — so it greets the operator on a cold start.
+  process.stdout.write(BANNER);
+
   const result = await planInit({
     argv,
     exists: defaultExists,

package/lib/cli/sync.js

@@ -242,7 +242,7 @@ export function runSync({
       write(`would prune ${path.join('.agents', rel)}\n`);
     }
     write(
-      `✅  Dry run: ${payloadFiles.length} file(s) would be materialized, ${stale.length} stale file(s) would be pruned from ./.agents/\n`,
+      `✅  Dry run: ${payloadFiles.length} file(s) would be installed, ${stale.length} stale file(s) would be pruned from ./.agents/\n`,
     );
     return {
       copied: 0,
@@ -275,10 +275,10 @@ export function runSync({
 
   if (staleFiles.length > 0) {
     write(
-      `✅  Materialized ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,
+      `✅  Installed ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,
     );
   } else {
-    write(`✅  Materialized ${payloadFiles.length} file(s) into ./.agents/\n`);
+    write(`✅  Installed ${payloadFiles.length} file(s) into ./.agents/\n`);
   }
   return {
     copied: payloadFiles.length,