@limina-labs/momentum 0.30.2

package/core/orchestration/types.js

@@ -0,0 +1,131 @@
+'use strict';
+
+// Structured result types for orchestration primitives.
+//
+// JSDoc-based — momentum is zero-dependency Node.js, no TypeScript at
+// build time. Helpers below provide light runtime shape validation
+// used by primitive implementations + tests.
+
+/**
+ * @typedef {object} Finding
+ * @property {'discovery'|'decision'|'note'} kind
+ * @property {string} title           Short human-readable title
+ * @property {string} [detail]        Multi-sentence description
+ * @property {string} [recommendedBacklogPriority]  P0|P1|P2|P3 if a backlog entry is warranted
+ * @property {string} [recommendedBacklogType]      bug|tech-debt|enhancement|feature
+ * @property {string[]} [filesTouched]
+ */
+
+/**
+ * @typedef {object} ScoutResult
+ * @property {string} repo               target repo path (absolute or relative to originating CWD)
+ * @property {string} prompt             user-provided scope prompt
+ * @property {string} summary            structured summary answering the prompt
+ * @property {Finding[]} findings        notable findings surfaced during the scout
+ * @property {string[]} filesRead        files inspected
+ * @property {number} duration           wall-clock milliseconds
+ * @property {string} runArtifactPath    absolute path to scout-NNN.md artifact
+ * @property {string} [sessionLogRef]    YYYY-MM-DD reference into ecosystem session log
+ * @property {object} [error]            present only when scout failed
+ */
+
+/**
+ * @typedef {object} PerRepoResult
+ * @property {string} repo
+ * @property {string} prompt           per-repo tailored prompt
+ * @property {string} [summary]
+ * @property {Finding[]} [findings]
+ * @property {string[]} [filesRead]
+ * @property {number} [duration]
+ * @property {object} [error]          present on failure
+ */
+
+/**
+ * @typedef {object} DispatchResult
+ * @property {string[]} repos
+ * @property {string} userIntent
+ * @property {'parallel'|'sequential'} mode
+ * @property {string[]} modeNotes            degraded-mode labels surfaced to the user
+ * @property {PerRepoResult[]} perRepoResults
+ * @property {PerRepoResult[]} failures      sub-agents that crashed; their entries also appear in perRepoResults with `error`
+ * @property {string} synthesis              top-level answer to userIntent
+ * @property {number} duration
+ * @property {string} runArtifactPath
+ * @property {string} [sessionLogRef]
+ */
+
+/**
+ * @typedef {object} HandoffBlock
+ * @property {string} fromRepo
+ * @property {string} toRepo
+ * @property {string} summary
+ * @property {string[]} decisions
+ * @property {string[]} filesTouched
+ * @property {string[]} verificationCommands
+ * @property {string[]} openQuestions
+ * @property {string} originatingPhase           e.g. "phase-11-orchestration-handover"
+ * @property {string} originatingHistoryRef      e.g. "[DECISION] 2026-06-07 — Handoff #042"
+ * @property {string} inboxPath                  absolute path to .momentum/inbox/handoff-NNN.md
+ * @property {string} handoffId                  monotonic id, e.g. "042"
+ * @property {string} createdAt                  ISO timestamp
+ */
+
+// ── Runtime shape validation (light) ────────────────────────────────────────
+//
+// These helpers exist to catch obvious shape mistakes in tests and at
+// runtime — not as a full type system. Validation is best-effort.
+
+function assertString(value, name) {
+  if (typeof value !== 'string') {
+    throw new TypeError(`orchestration/types: ${name} must be a string, got ${typeof value}`);
+  }
+}
+
+function assertArray(value, name) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(`orchestration/types: ${name} must be an array, got ${typeof value}`);
+  }
+}
+
+function validateScoutResult(result) {
+  assertString(result.repo, 'ScoutResult.repo');
+  assertString(result.prompt, 'ScoutResult.prompt');
+  assertString(result.summary, 'ScoutResult.summary');
+  assertArray(result.findings, 'ScoutResult.findings');
+  assertArray(result.filesRead, 'ScoutResult.filesRead');
+  if (typeof result.duration !== 'number') {
+    throw new TypeError('ScoutResult.duration must be a number');
+  }
+  return result;
+}
+
+function validateDispatchResult(result) {
+  assertArray(result.repos, 'DispatchResult.repos');
+  assertString(result.userIntent, 'DispatchResult.userIntent');
+  if (result.mode !== 'parallel' && result.mode !== 'sequential') {
+    throw new TypeError(`DispatchResult.mode must be 'parallel'|'sequential', got ${result.mode}`);
+  }
+  assertArray(result.modeNotes, 'DispatchResult.modeNotes');
+  assertArray(result.perRepoResults, 'DispatchResult.perRepoResults');
+  assertArray(result.failures, 'DispatchResult.failures');
+  assertString(result.synthesis, 'DispatchResult.synthesis');
+  return result;
+}
+
+function validateHandoffBlock(block) {
+  assertString(block.fromRepo, 'HandoffBlock.fromRepo');
+  assertString(block.toRepo, 'HandoffBlock.toRepo');
+  assertString(block.summary, 'HandoffBlock.summary');
+  assertArray(block.decisions, 'HandoffBlock.decisions');
+  assertArray(block.filesTouched, 'HandoffBlock.filesTouched');
+  assertArray(block.verificationCommands, 'HandoffBlock.verificationCommands');
+  assertArray(block.openQuestions, 'HandoffBlock.openQuestions');
+  assertString(block.handoffId, 'HandoffBlock.handoffId');
+  return block;
+}
+
+module.exports = {
+  validateScoutResult,
+  validateDispatchResult,
+  validateHandoffBlock,
+};

package/core/scripts/brainstorm-gate.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# brainstorm-gate.sh — PreToolUse hook (shared across Claude Code + Codex + Antigravity)
+#
+# Blocks write-class tool calls targeting paths under specs/ while a
+# brainstorm session is active (indicated by the .momentum/brainstorm-active
+# sentinel file).
+#
+# Phase 16 Rework: promoted from adapters/claude-code/scripts/ to
+# core/scripts/ and generalized to handle all three adapters' native tool
+# names and payload shapes.
+#
+# Tool names matched per platform:
+#   Claude Code: Write, Edit, MultiEdit
+#   Codex:       apply_patch, Bash
+#   Antigravity: run_command, view_file, *write*, apply_patch
+#
+# Project root resolution (in order):
+#   1. MOMENTUM_PROJECT_DIR (explicit override)
+#   2. CLAUDE_PROJECT_DIR (Claude Code sets this)
+#   3. PWD (Codex + Antigravity hooks run with cwd = session root)
+#
+# Exit codes:
+#   0 — allow the tool call (default; also used for fail-open paths)
+#   2 — block the tool call (stderr is shown to the model)
+
+set -euo pipefail
+
+# ---------------------------------------------------------------------------
+# 1. Read hook input (JSON on stdin)
+# ---------------------------------------------------------------------------
+input=$(cat)
+
+# ---------------------------------------------------------------------------
+# 2. Extract tool_name + file path from payload.
+#
+# Payload shapes we handle:
+#   - Claude Code:  {tool_name, tool_input: {file_path: "..."}}
+#   - Codex apply_patch:  {tool_name: "apply_patch", tool_input: {input: "*** Update File: <path>\n..."}}
+#   - Codex Bash:         {tool_name: "Bash", tool_input: {command: "..."}}
+#   - Antigravity:        {tool_name, tool_input: {path: "...", command?: "..."}}
+#
+# Strategy: try jq first (best precision), fall back to grep/sed.
+# Extract `file_path` (Claude / Antigravity) OR `path` (Antigravity) OR
+# the first `*** Update File:` / `*** Add File:` line from `input` (Codex apply_patch).
+# ---------------------------------------------------------------------------
+if command -v jq >/dev/null 2>&1; then
+  tool_name=$(printf '%s' "$input" | jq -r '.tool_name // empty' 2>/dev/null || true)
+  file_path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty' 2>/dev/null || true)
+  if [[ -z "${file_path:-}" ]]; then
+    # Antigravity uses `path` instead of `file_path` for some tools
+    file_path=$(printf '%s' "$input" | jq -r '.tool_input.path // empty' 2>/dev/null || true)
+  fi
+  if [[ -z "${file_path:-}" ]]; then
+    # Codex apply_patch — extract from input
+    patch_input=$(printf '%s' "$input" | jq -r '.tool_input.input // empty' 2>/dev/null || true)
+    if [[ -n "$patch_input" ]]; then
+      file_path=$(printf '%s' "$patch_input" \
+        | grep -oE '\*\*\* (Update|Add|Delete) File: [^ ]+' \
+        | head -1 \
+        | sed -E 's/\*\*\* (Update|Add|Delete) File: //' || true)
+    fi
+  fi
+  if [[ -z "${file_path:-}" ]]; then
+    # Last resort — look for shell command targeting specs/
+    cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty' 2>/dev/null || true)
+    if [[ -n "$cmd" ]]; then
+      # Match: `> specs/path`, `>> specs/path`, `echo ... specs/path`, etc.
+      file_path=$(printf '%s' "$cmd" \
+        | grep -oE '(specs/[^[:space:]"'"'"'\\]+)' \
+        | head -1 || true)
+    fi
+  fi
+else
+  # No jq — regex fallbacks. Brittle but adequate for canonical shapes.
+  tool_name=$(printf '%s' "$input" \
+    | grep -oE '"tool_name"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 \
+    | sed -E 's/.*:[[:space:]]*"([^"]+)"$/\1/' || true)
+  file_path=$(printf '%s' "$input" \
+    | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 \
+    | sed -E 's/.*:[[:space:]]*"([^"]+)"$/\1/' || true)
+  if [[ -z "${file_path:-}" ]]; then
+    file_path=$(printf '%s' "$input" \
+      | grep -oE '"path"[[:space:]]*:[[:space:]]*"[^"]*"' \
+      | head -1 \
+      | sed -E 's/.*:[[:space:]]*"([^"]+)"$/\1/' || true)
+  fi
+  if [[ -z "${file_path:-}" ]]; then
+    # Codex apply_patch path extraction (string-mode escapes)
+    file_path=$(printf '%s' "$input" \
+      | grep -oE '\*\*\* (Update|Add|Delete) File: [^\\"]+' \
+      | head -1 \
+      | sed -E 's/\*\*\* (Update|Add|Delete) File: //' || true)
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# 3. Allow non-write tool calls
+#    Match Claude Code (Write/Edit/MultiEdit), Codex (apply_patch/Bash),
+#    Antigravity (run_command/view_file/*write*/apply_patch).
+# ---------------------------------------------------------------------------
+case "${tool_name:-}" in
+  Write|Edit|MultiEdit) ;;        # Claude Code
+  apply_patch|Bash) ;;             # Codex (per docs: canonical tool_name is "Bash" for shell)
+  run_command|view_file) ;;        # Antigravity (matcher includes these)
+  *write*) ;;                      # Antigravity wildcard
+  *) exit 0 ;;
+esac
+
+# ---------------------------------------------------------------------------
+# 4. Resolve project root.
+#    MOMENTUM_PROJECT_DIR (override) → CLAUDE_PROJECT_DIR → PWD.
+# ---------------------------------------------------------------------------
+project_dir="${MOMENTUM_PROJECT_DIR:-${CLAUDE_PROJECT_DIR:-${PWD:-}}}"
+if [[ -z "${project_dir}" || ! -d "${project_dir}" ]]; then
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# 5. Sentinel check — if the brainstorm-active sentinel is missing, allow.
+# ---------------------------------------------------------------------------
+sentinel="${project_dir}/.momentum/brainstorm-active"
+if [[ ! -e "$sentinel" ]]; then
+  exit 0
+fi
+
+# ---------------------------------------------------------------------------
+# 6. Path check — only block writes under specs/.
+# ---------------------------------------------------------------------------
+if [[ -z "${file_path:-}" ]]; then
+  exit 0  # fail-open if path missing
+fi
+
+# Resolve relative paths against project_dir
+case "$file_path" in
+  /*) abs_path="$file_path" ;;
+  *)  abs_path="${project_dir}/${file_path}" ;;
+esac
+
+specs_dir="${project_dir}/specs/"
+case "$abs_path" in
+  "${specs_dir}"*)
+    cat >&2 <<EOF
+[brainstorm-gate] Blocked: cannot write to specs/ during active brainstorm.
+[brainstorm-gate] Path: ${file_path}
+[brainstorm-gate]
+[brainstorm-gate] The conversation IS the draft. Get explicit user approval, then:
+[brainstorm-gate]   rm .momentum/brainstorm-active
+[brainstorm-gate] and retry the write.
+EOF
+    exit 2
+    ;;
+  *)
+    exit 0
+    ;;
+esac

package/core/scripts/check-history-reminder.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# Read-only hook: reminds Claude to log history when significant files
+# change, AND best-effort appends to today's ecosystem session log when
+# this repo is a registered member.
+
+set -euo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name',''))" 2>/dev/null || echo "")
+FILE_PATH=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null || echo "")
+TOOL_COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_input',{}).get('command',''))" 2>/dev/null || echo "")
+
+# ── Phase-history reminder (file edits) ──────────────────────────────────
+
+if [ -n "$FILE_PATH" ]; then
+  SIGNIFICANT=false
+  case "$FILE_PATH" in
+    specs/decisions/*.md)       SIGNIFICANT=true ;;
+    specs/phases/*/tasks.md)    SIGNIFICANT=true ;;
+    specs/adhoc/*/record.md)    SIGNIFICANT=true ;;
+    specs/backlog/backlog.md)   SIGNIFICANT=true ;;
+    specs/status.md)            SIGNIFICANT=true ;;
+    specs/architecture/*.md)    SIGNIFICANT=true ;;
+  esac
+
+  if [ "$SIGNIFICANT" = "true" ]; then
+    # ── Lane binding (Rule 15): resolve the phase from the current branch.
+    # phase-* branch with a matching specs/phases/<branch>/ dir wins;
+    # non-phase branch → ad-hoc sink; detached HEAD or no match → fall back
+    # to the status.md Active Phase table (first row with an existing dir).
+    BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+    PHASE_DIR=""
+    PHASE_SOURCE=""
+    if [ -n "$BRANCH" ]; then
+      case "$BRANCH" in
+        phase-*)
+          if [ -d "specs/phases/$BRANCH" ]; then
+            PHASE_DIR="specs/phases/$BRANCH"
+            PHASE_SOURCE="branch"
+          fi
+          ;;
+        *)
+          PHASE_SOURCE="adhoc"
+          ;;
+      esac
+    fi
+    if [ -z "$PHASE_DIR" ] && [ "$PHASE_SOURCE" != "adhoc" ] && [ -f "specs/status.md" ]; then
+      while IFS= read -r candidate; do
+        if [ -d "specs/phases/$candidate" ]; then
+          PHASE_DIR="specs/phases/$candidate"
+          PHASE_SOURCE="status"
+          break
+        fi
+      done < <(awk '/^## Active Phase/{f=1;next} /^## /{f=0} f' specs/status.md \
+        | grep -E '^\|' | grep -oE '\`phase-[A-Za-z0-9._-]+\`' | tr -d '\`' || true)
+    fi
+
+    if [ "$PHASE_SOURCE" = "branch" ]; then
+      echo "HISTORY REMINDER: '$FILE_PATH' was modified — if this reflects a decision, scope change, or discovery, append an entry to your lane's history file ($PHASE_DIR/history.md — the phase bound to branch '$BRANCH', Rule 15)."
+    elif [ "$PHASE_SOURCE" = "status" ]; then
+      echo "HISTORY REMINDER: '$FILE_PATH' was modified — if this reflects a decision, scope change, or discovery, append an entry to the active phase history ($PHASE_DIR/history.md — resolved from the status.md Active Phase table; the current branch does not bind to a phase directory)."
+    elif [ "$PHASE_SOURCE" = "adhoc" ]; then
+      echo "HISTORY REMINDER: '$FILE_PATH' was modified on non-phase branch '$BRANCH' — if this reflects a decision, scope change, or discovery, append an entry to the ad-hoc record (specs/adhoc/<id>/record.md) or specs/adhoc/history.md."
+    else
+      echo "HISTORY REMINDER: '$FILE_PATH' was modified — if this reflects a decision, scope change, or discovery, append an entry to the active phase history file (specs/phases/<active-phase>/history.md), or — when no phase is active — to the ad-hoc record (specs/adhoc/<id>/record.md) or specs/adhoc/history.md."
+    fi
+  fi
+fi
+
+# ── Ecosystem session-log auto-append (best-effort) ─────────────────────
+# When this hook fires after a `git commit` or `gh pr ...` Bash command,
+# record one line to today's session log if this repo is a registered
+# ecosystem member. Silent no-op otherwise (no ecosystem, no member id,
+# no helper script — all cases just exit cleanly).
+
+session_append() {
+  local script_dir
+  script_dir=$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")
+  local session_script=""
+  # Try common locations: peer ecosystem/scripts/ dir,
+  # in-repo nested copy, or sibling.
+  for candidate in \
+    "$script_dir/../ecosystem/scripts/session-append.sh" \
+    "$script_dir/ecosystem/scripts/session-append.sh" \
+    "$script_dir/session-append.sh"; do
+    if [ -x "$candidate" ]; then
+      session_script="$candidate"
+      break
+    fi
+  done
+  [ -z "$session_script" ] && return 0
+  "$session_script" "$@" 2>/dev/null || true
+}
+
+if [ "$TOOL_NAME" = "Bash" ] && [ -n "$TOOL_COMMAND" ]; then
+  case "$TOOL_COMMAND" in
+    *"git commit"*)
+      sha=$(git rev-parse --short HEAD 2>/dev/null || echo "")
+      subject=$(git log -1 --pretty=%s 2>/dev/null || echo "")
+      if [ -n "$sha" ] && [ -n "$subject" ]; then
+        session_append "commit" "$subject" "$sha"
+      fi
+      ;;
+    *"gh pr merge"*|*"gh pr create"*)
+      session_append "pr" "$(echo "$TOOL_COMMAND" | head -c 80)" ""
+      ;;
+  esac
+fi
+
+exit 0

package/core/scripts/sessionstart-handoff.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# SessionStart hook — momentum context + handoff auto-greet.
+#
+# Two banners, printed in this order to stderr:
+#
+#   1. Ecosystem context (ENH-033, Phase 15) — when CWD is reachable
+#      from an ecosystem.json (parent walk + sibling scan), one or two
+#      lines naming the ecosystem, member count, and active initiative.
+#
+#   2. Handoff inbox — when `.momentum/inbox/handoff-*.md` exists, one
+#      line per pending handoff. Final line prompts the user
+#      `Read now? [y/skip]`; on `y` the script exits 10 to signal the
+#      adapter that the next agent action should be `/continue` (or
+#      `momentum continue`). On any other input or non-TTY runs, exits
+#      0 silently — the handoff stays in the inbox until the user runs
+#      `/continue` themselves.
+#
+# Both banners are silent when not relevant. Total cost target <100ms.
+#
+# Adapter wiring:
+#   - Claude Code:  .claude/settings.json SessionStart entry → this script
+#   - Codex:        .codex/hooks.json SessionStart entry → this script
+#   - Antigravity:  no SessionStart hook surface; banners ship via
+#                   primary instruction text (see overlay).
+
+set -eu
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Banner 1 — Ecosystem context (ENH-033)
+# ─────────────────────────────────────────────────────────────────────────────
+#
+# Mirror the parent-walk + sibling-scan algorithm from
+# core/ecosystem/scripts/session-append.sh so what the session log
+# considers "the reachable ecosystem" is what the SessionStart banner
+# announces.
+
+find_ecosystem_root() {
+  local current="$PWD"
+  local depth=0
+  local max_depth="${MOMENTUM_MAX_PARENT_WALK:-5}"
+  case "$max_depth" in
+    ''|*[!0-9]*) max_depth=5 ;;
+  esac
+  while [ $depth -le $max_depth ]; do
+    # Same-directory check (caller might already be in ecosystem root)
+    if [ -f "$current/ecosystem.json" ]; then
+      echo "$current"
+      return 0
+    fi
+    # Sibling check
+    local parent
+    parent=$(dirname "$current")
+    if [ "$parent" = "$current" ]; then return 1; fi
+    for sibling in "$parent"/*; do
+      if [ -d "$sibling" ] && [ -f "$sibling/ecosystem.json" ]; then
+        echo "$sibling"
+        return 0
+      fi
+    done
+    current="$parent"
+    depth=$((depth + 1))
+  done
+  return 1
+}
+
+# Best-effort: silent on any failure so a broken ecosystem.json never
+# blocks the session.
+ECO_ROOT="$(find_ecosystem_root 2>/dev/null || true)"
+
+if [ -n "${ECO_ROOT:-}" ] && [ -f "$ECO_ROOT/ecosystem.json" ]; then
+  # Extract name + member count. Prefer python3 for JSON parsing; fall
+  # back to grep/sed when python3 isn't available (rare but possible).
+  if command -v python3 >/dev/null 2>&1; then
+    eco_summary=$(python3 - "$ECO_ROOT/ecosystem.json" <<'PY' 2>/dev/null || echo ""
+import sys, json
+try:
+    with open(sys.argv[1]) as f:
+        m = json.load(f)
+    name = m.get("name", "(unnamed)")
+    members = len(m.get("members", []) or [])
+    print(f"{name}\t{members}")
+except Exception:
+    pass
+PY
+)
+  else
+    # Crude fallback — extract `"name": "..."` and count `"id":` entries.
+    eco_name=$(sed -nE 's/.*"name"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' "$ECO_ROOT/ecosystem.json" | head -1)
+    eco_members=$(grep -cE '"id"[[:space:]]*:' "$ECO_ROOT/ecosystem.json" || echo 0)
+    eco_summary="${eco_name:-(unnamed)}	${eco_members}"
+  fi
+
+  if [ -n "${eco_summary:-}" ]; then
+    eco_name=$(printf '%s' "$eco_summary" | cut -f1)
+    eco_members=$(printf '%s' "$eco_summary" | cut -f2)
+    if [ "$eco_members" = "1" ]; then
+      plural=""
+    else
+      plural="s"
+    fi
+    printf '▸ Ecosystem: %s (%s member%s)\n' "$eco_name" "$eco_members" "$plural" >&2
+
+    # Active initiative line (only when set).
+    if [ -f "$ECO_ROOT/.state/active-initiative" ]; then
+      active=$(tr -d '\n' < "$ECO_ROOT/.state/active-initiative" 2>/dev/null | head -c 200)
+      if [ -n "$active" ]; then
+        printf '▸ Active initiative: %s\n' "$active" >&2
+      fi
+    fi
+  fi
+fi
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Banner 2 — Handoff inbox (existing behaviour)
+# ─────────────────────────────────────────────────────────────────────────────
+
+INBOX_DIR=".momentum/inbox"
+
+# No inbox dir → no pending handoffs.
+[ -d "$INBOX_DIR" ] || exit 0
+
+# Walk the inbox and collect pending handoff files.
+shopt -s nullglob 2>/dev/null || true
+pending=( "$INBOX_DIR"/handoff-*.md )
+if [ "${#pending[@]}" -eq 0 ]; then
+  exit 0
+fi
+
+count="${#pending[@]}"
+if [ "$count" -eq 1 ]; then
+  plural=""
+else
+  plural="s"
+fi
+banner_lines=()
+banner_lines+=( "▸ ${count} pending handoff${plural}:" )
+
+for f in "${pending[@]}"; do
+  base=$(basename "$f" .md)
+  # Pull a one-line summary from the inbox file. Use awk to grab the
+  # line after `## Summary` heading. Fallback to filename if missing.
+  summary=$(awk '/^## Summary$/{getline; print; exit}' "$f" 2>/dev/null || true)
+  [ -z "$summary" ] && summary="(no summary)"
+  from=$(awk -F': *' '/^\*\*fromRepo:\*\*/ {print $2; exit}' "$f" 2>/dev/null || true)
+  if [ -n "$from" ]; then
+    from_label=$(basename "$from")
+  else
+    from_label="(unknown)"
+  fi
+  banner_lines+=( "  ▸ ${base} from ${from_label}: ${summary}" )
+done
+
+banner_lines+=( "▸ Read now? [y/skip]  (or run: /continue / momentum continue)" )
+
+# Emit the banner. Use stderr so the agent's primary stdout stays
+# clean for normal output; adapters that route hook output anywhere
+# will still surface it.
+for line in "${banner_lines[@]}"; do
+  printf '%s\n' "$line" >&2
+done
+
+# If stdin is not a TTY (CI, agent harness without interactive surface)
+# just exit 0 — the banner has informed the user (or downstream
+# adapter) without forcing a blocking read.
+if [ ! -t 0 ]; then
+  exit 0
+fi
+
+# Read a single character with a short timeout so we don't hang an
+# unattended session start.
+ans=""
+if IFS= read -t 5 -r -n 1 ans 2>/dev/null; then
+  : # read succeeded (ans may be empty if user hit Enter)
+fi
+printf '\n' >&2
+
+case "$ans" in
+  y|Y) exit 10 ;;
+  *)   exit 0  ;;
+esac