@lumenflow/cli 3.1.3 → 3.2.1

package/dist/hooks/generators/enforce-worktree.js

@@ -0,0 +1,190 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/enforce-worktree.ts
+ * Generate the enforce-worktree.sh hook script content (WU-1367, WU-1501).
+ *
+ * Extracted from enforcement-generator.ts by WU-1645.
+ */
+/**
+ * Generate the enforce-worktree.sh hook script content.
+ *
+ * WU-1501: Fail-closed on main. Blocks Write/Edit when no active claim context.
+ * Graceful degradation only when LumenFlow is NOT configured.
+ * Allowlist: docs/04-operations/tasks/wu/, .lumenflow/, .claude/, plan/
+ * Branch-PR claimed_mode remains writable from main checkout.
+ */
+export function generateEnforceWorktreeScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# enforce-worktree.sh (WU-1367, WU-1501)
+#
+# PreToolUse hook that blocks Write/Edit on main checkout.
+# WU-1501: Fail-closed - blocks even when no worktrees exist.
+# Graceful degradation only when LumenFlow is NOT configured.
+#
+# Allowlist: docs/04-operations/tasks/wu/, .lumenflow/, .claude/, plan/
+# Branch-PR claimed_mode permits writes from main checkout.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (stderr shown to Claude as guidance)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Graceful degradation: if we can't determine state, allow the operation
+graceful_allow() {
+  local reason="\$1"
+  exit 0
+}
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  graceful_allow "CLAUDE_PROJECT_DIR not set"
+fi
+
+MAIN_REPO_PATH="\$CLAUDE_PROJECT_DIR"
+WORKTREES_DIR="\${MAIN_REPO_PATH}/worktrees"
+LUMENFLOW_DIR="\${MAIN_REPO_PATH}/.lumenflow"
+
+# Check if .lumenflow exists (LumenFlow is configured)
+if [[ ! -d "\$LUMENFLOW_DIR" ]]; then
+  graceful_allow "No .lumenflow directory (LumenFlow not configured)"
+fi
+
+# Read JSON input from stdin
+INPUT=\$(cat)
+
+if [[ -z "\$INPUT" ]]; then
+  graceful_allow "No input provided"
+fi
+
+# Parse JSON with Python
+TMPFILE=\$(mktemp)
+echo "\$INPUT" > "\$TMPFILE"
+
+PARSE_RESULT=\$(python3 -c "
+import json
+import sys
+try:
+    with open('\$TMPFILE', 'r') as f:
+        data = json.load(f)
+    tool_name = data.get('tool_name', '')
+    tool_input = data.get('tool_input', {})
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    file_path = tool_input.get('file_path', '')
+    print('OK')
+    print(tool_name if tool_name else '')
+    print(file_path if file_path else '')
+except Exception as e:
+    print('ERROR')
+    print(str(e))
+    print('')
+" 2>&1)
+
+rm -f "\$TMPFILE"
+
+# Parse the result
+PARSE_STATUS=\$(echo "\$PARSE_RESULT" | head -1)
+TOOL_NAME=\$(echo "\$PARSE_RESULT" | sed -n '2p')
+FILE_PATH=\$(echo "\$PARSE_RESULT" | sed -n '3p')
+
+if [[ "\$PARSE_STATUS" != "OK" ]]; then
+  graceful_allow "JSON parse failed"
+fi
+
+# Only process Write and Edit tools
+if [[ "\$TOOL_NAME" != "Write" && "\$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+if [[ -z "\$FILE_PATH" ]]; then
+  graceful_allow "No file_path in input"
+fi
+
+# Resolve the file path
+RESOLVED_PATH=\$(realpath -m "\$FILE_PATH" 2>/dev/null || echo "\$FILE_PATH")
+
+# Allow if path is outside repo entirely
+if [[ "\$RESOLVED_PATH" != "\${MAIN_REPO_PATH}/"* && "\$RESOLVED_PATH" != "\${MAIN_REPO_PATH}" ]]; then
+  exit 0
+fi
+
+# Allow if path is inside a worktree
+if [[ "\$RESOLVED_PATH" == "\${WORKTREES_DIR}/"* ]]; then
+  exit 0
+fi
+
+# Check if UnsafeAny active worktrees exist
+WORKTREE_COUNT=0
+if [[ -d "\$WORKTREES_DIR" ]]; then
+  WORKTREE_COUNT=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+fi
+
+# If worktrees exist, block writes to main repo (original behavior)
+if [[ "\$WORKTREE_COUNT" -gt 0 ]]; then
+  ACTIVE_WORKTREES=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d -printf '%f\\n' 2>/dev/null | head -5 | tr '\\n' ', ' | sed 's/,\$//')
+
+  echo "" >&2
+  echo "=== Worktree Enforcement ===" >&2
+  echo "" >&2
+  echo "BLOCKED: \$TOOL_NAME to main repo" >&2
+  echo "" >&2
+  echo "Active worktrees: \${ACTIVE_WORKTREES:-none detected}" >&2
+  echo "" >&2
+  echo "USE INSTEAD:" >&2
+  echo "  1. cd to your worktree: cd worktrees/<lane>-wu-<id>/" >&2
+  echo "  2. Make your edits in the worktree" >&2
+  echo "" >&2
+  echo "See: LUMENFLOW.md for worktree discipline" >&2
+  echo "==============================" >&2
+  exit 2
+fi
+
+# WU-1501: Fail-closed on main when no active worktrees exist
+# Check allowlist: paths that are always safe to write on main
+RELATIVE_PATH="\${RESOLVED_PATH#\${MAIN_REPO_PATH}/}"
+
+case "\$RELATIVE_PATH" in
+  docs/04-operations/tasks/wu/*)  exit 0 ;;  # WU YAML specs
+  .lumenflow/*)                   exit 0 ;;  # LumenFlow state/config
+  .claude/*)                      exit 0 ;;  # Claude Code config
+  plan/*)                         exit 0 ;;  # Plan/spec scaffolds
+esac
+
+# Check for branch-pr claimed_mode (allows main writes without worktree)
+STATE_FILE="\${LUMENFLOW_DIR}/state/wu-events.jsonl"
+if [[ -f "\$STATE_FILE" ]]; then
+  if grep -q '"claimed_mode":"branch-pr"' "\$STATE_FILE" 2>/dev/null; then
+    if grep -q '"status":"in_progress"' "\$STATE_FILE" 2>/dev/null; then
+      exit 0  # Branch-PR WU active - allow main writes
+    fi
+  fi
+fi
+
+# WU-1501: Fail-closed - no active claim context, block the write
+echo "" >&2
+echo "=== Worktree Enforcement ===" >&2
+echo "" >&2
+echo "BLOCKED: \$TOOL_NAME on main (no active WU claim)" >&2
+echo "" >&2
+echo "No worktrees exist and no branch-pr WU is in progress." >&2
+echo "" >&2
+echo "WHAT TO DO:" >&2
+echo "  1. Claim a WU: pnpm wu:claim --id WU-XXXX --lane \\"<Lane>\\"" >&2
+echo "  2. cd worktrees/<lane>-wu-xxxx" >&2
+echo "  3. Make your edits in the worktree" >&2
+echo "" >&2
+echo "See: LUMENFLOW.md for worktree discipline" >&2
+echo "==============================" >&2
+exit 2
+`;
+    /* eslint-enable no-useless-escape */
+}
+//# sourceMappingURL=enforce-worktree.js.map

package/dist/hooks/generators/enforce-worktree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce-worktree.js","sourceRoot":"","sources":["../../../src/hooks/generators/enforce-worktree.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,6BAA6B;IAC3C,sFAAsF;IACtF,sCAAsC;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuKR,CAAC;IACA,qCAAqC;AACvC,CAAC"}

package/dist/hooks/generators/index.js

@@ -0,0 +1,18 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/index.ts
+ * Barrel export for per-hook generator modules (WU-1645).
+ *
+ * Each hook script builder lives in its own file for focused maintainability.
+ * This barrel re-exports all generators so that enforcement-generator.ts
+ * (and other consumers) can import from a single location.
+ */
+export { generateEnforceWorktreeScript } from './enforce-worktree.js';
+export { generateRequireWuScript } from './require-wu.js';
+export { generateWarnIncompleteScript } from './warn-incomplete.js';
+export { generatePreCompactCheckpointScript } from './pre-compact-checkpoint.js';
+export { generateSessionStartRecoveryScript } from './session-start-recovery.js';
+export { generateAutoCheckpointScript } from './auto-checkpoint.js';
+export { surfaceUnreadSignals, markCompletedWUSignalsAsRead, } from './signal-utils.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/generators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hooks/generators/index.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;;;GAOG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAAE,kCAAkC,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAAE,4BAA4B,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,EACL,oBAAoB,EACpB,4BAA4B,GAG7B,MAAM,mBAAmB,CAAC"}

package/dist/hooks/generators/pre-compact-checkpoint.js

@@ -0,0 +1,136 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/pre-compact-checkpoint.ts
+ * Generate the pre-compact-checkpoint.sh hook script content (WU-1394).
+ *
+ * Extracted from enforcement-generator.ts by WU-1645.
+ */
+/**
+ * Generate the pre-compact-checkpoint.sh hook script content.
+ *
+ * This PreCompact hook saves a checkpoint and writes a durable recovery file
+ * before context compaction. The recovery file survives compaction and is
+ * read by session-start-recovery.sh on the next session start.
+ *
+ * Part of WU-1394: Durable recovery pattern for context preservation.
+ */
+export function generatePreCompactCheckpointScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# pre-compact-checkpoint.sh
+#
+# PreCompact hook - auto-checkpoint + durable recovery marker (WU-1390)
+#
+# Fires before context compaction to:
+# 1. Save a checkpoint with the current WU progress
+# 2. Write a durable recovery file that survives compaction
+#
+# The recovery file is read by session-start-recovery.sh on the next
+# session start (after compact, resume, or clear) to restore context.
+#
+# Exit codes:
+#   0 = Always allow (cannot block compaction)
+#
+# Uses python3 for JSON parsing (consistent with other hooks)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="\$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=\$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "\$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+# Read JSON input from stdin
+INPUT=\$(cat)
+
+# Parse trigger from hook input (defensive - default to "auto")
+# PreCompact provides: { "trigger": "manual" | "auto" }
+TRIGGER=\$(python3 -c "
+import json
+import sys
+try:
+    data = json.loads('''\$INPUT''')
+    trigger = data.get('trigger', 'auto')
+    print(trigger if trigger else 'auto')
+except:
+    print('auto')
+" 2>/dev/null || echo "auto")
+
+# Get WU ID from worktree context (wu:status --json)
+# Location.worktreeWuId is set when in a worktree
+WU_ID=\$(pnpm wu:status --json 2>/dev/null | python3 -c "
+import json
+import sys
+try:
+    data = json.load(sys.stdin)
+    location = data.get('location', {})
+    wu_id = location.get('worktreeWuId') or ''
+    print(wu_id)
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+# Proceed with worktree-based recovery if we have a WU ID
+if [[ -n "\$WU_ID" ]]; then
+  # Save checkpoint with pre-compact trigger
+  # Note: This may fail if CLI not built, but that's OK - recovery file is more important
+  pnpm mem:checkpoint "Auto: pre-\${TRIGGER}-compaction" --wu "\$WU_ID" --trigger "pre-compact" --quiet 2>/dev/null || true
+
+  # Write durable recovery marker (survives compaction)
+  # This is the key mechanism - file persists and is read by session-start-recovery.sh
+  RECOVERY_DIR="\${REPO_PATH}/.lumenflow/state"
+  RECOVERY_FILE="\${RECOVERY_DIR}/recovery-pending-\${WU_ID}.md"
+
+  mkdir -p "\$RECOVERY_DIR"
+
+  # Generate recovery context using mem:recover
+  # The --quiet flag outputs only the recovery context without headers
+  pnpm mem:recover --wu "\$WU_ID" --quiet > "\$RECOVERY_FILE" 2>/dev/null || {
+    # Fallback minimal recovery if mem:recover fails
+    cat > "\$RECOVERY_FILE" << EOF
+# POST-COMPACTION RECOVERY
+
+You are resuming work after context compaction. Your previous context was lost.
+**WU:** \${WU_ID}
+
+## Next Action
+Run \\\`pnpm wu:brief --id \${WU_ID} --client \${LUMENFLOW_CLIENT:-claude-code}\\\` to generate a fresh handoff prompt.
+EOF
+  }
+
+  # Output brief warning to stderr (may be compacted away, but recovery file persists)
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  COMPACTION: Checkpoint saved for \${WU_ID}" >&2
+  echo "Recovery context: \${RECOVERY_FILE}" >&2
+  echo "Next: pnpm wu:brief --id \${WU_ID} --client \${LUMENFLOW_CLIENT:-claude-code}" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+else
+  # WU-1473: Non-worktree orchestrator context recovery
+  # When not in a worktree (e.g., orchestrator on main), surface unread inbox
+  # so agents have coordination context after compaction
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  COMPACTION: No active WU detected (non-worktree context)" >&2
+  echo "Surfacing recent coordination signals via mem:inbox..." >&2
+  pnpm mem:inbox --since 1h --quiet 2>/dev/null >&2 || true
+  echo "═══════════════════════════════════════════════════════" >&2
+fi
+
+# Always exit 0 - cannot block compaction
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}
+//# sourceMappingURL=pre-compact-checkpoint.js.map

package/dist/hooks/generators/pre-compact-checkpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pre-compact-checkpoint.js","sourceRoot":"","sources":["../../../src/hooks/generators/pre-compact-checkpoint.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC;IAChD,sFAAsF;IACtF,sCAAsC;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgHR,CAAC;IACA,qCAAqC;AACvC,CAAC"}

package/dist/hooks/generators/require-wu.js

@@ -0,0 +1,117 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/require-wu.ts
+ * Generate the require-wu.sh hook script content (WU-1367).
+ *
+ * Extracted from enforcement-generator.ts by WU-1645.
+ */
+/**
+ * Generate the require-wu.sh hook script content.
+ *
+ * This hook blocks Write/Edit operations when no WU is claimed.
+ * Implements graceful degradation: allows operations if LumenFlow
+ * state cannot be determined.
+ */
+export function generateRequireWuScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# require-wu.sh (WU-1367)
+#
+# PreToolUse hook that blocks Write/Edit when no WU is claimed.
+# Graceful degradation: allows operations if state cannot be determined.
+#
+# Exit codes:
+#   0 = Allow operation
+#   2 = Block operation (stderr shown to Claude as guidance)
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
+
+# Graceful degradation
+graceful_allow() {
+  local reason="\$1"
+  exit 0
+}
+
+if [[ -z "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  graceful_allow "CLAUDE_PROJECT_DIR not set"
+fi
+
+MAIN_REPO_PATH="\$CLAUDE_PROJECT_DIR"
+WORKTREES_DIR="\${MAIN_REPO_PATH}/worktrees"
+LUMENFLOW_DIR="\${MAIN_REPO_PATH}/.lumenflow"
+STATE_FILE="\${LUMENFLOW_DIR}/state/wu-events.jsonl"
+
+# Check if LumenFlow is configured
+if [[ ! -d "\$LUMENFLOW_DIR" ]]; then
+  graceful_allow "No .lumenflow directory"
+fi
+
+# Read JSON input
+INPUT=\$(cat)
+if [[ -z "\$INPUT" ]]; then
+  graceful_allow "No input"
+fi
+
+# Parse JSON
+TMPFILE=\$(mktemp)
+echo "\$INPUT" > "\$TMPFILE"
+
+TOOL_NAME=\$(python3 -c "
+import json
+try:
+    with open('\$TMPFILE', 'r') as f:
+        data = json.load(f)
+    print(data.get('tool_name', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+rm -f "\$TMPFILE"
+
+# Only check Write and Edit
+if [[ "\$TOOL_NAME" != "Write" && "\$TOOL_NAME" != "Edit" ]]; then
+  exit 0
+fi
+
+# Check for active worktrees (indicates claimed WU)
+if [[ -d "\$WORKTREES_DIR" ]]; then
+  WORKTREE_COUNT=\$(find "\$WORKTREES_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | wc -l)
+  if [[ "\$WORKTREE_COUNT" -gt 0 ]]; then
+    exit 0  # Has worktrees = has claimed WU
+  fi
+fi
+
+# Check state file for in_progress WUs
+if [[ -f "\$STATE_FILE" ]]; then
+  # Look for UnsafeAny WU with in_progress status
+  if grep -q '"status":"in_progress"' "\$STATE_FILE" 2>/dev/null; then
+    exit 0  # Has in_progress WU
+  fi
+fi
+
+# No claimed WU found
+echo "" >&2
+echo "=== WU Enforcement ===" >&2
+echo "" >&2
+echo "BLOCKED: \$TOOL_NAME without claimed WU" >&2
+echo "" >&2
+echo "You must claim a WU before making edits:" >&2
+echo "  pnpm wu:claim --id WU-XXXX --lane <Lane>" >&2
+echo "  cd worktrees/<lane>-wu-xxxx" >&2
+echo "" >&2
+echo "Or create a new WU:" >&2
+echo "  pnpm wu:create --lane <Lane> --title \"Description\"" >&2
+echo "" >&2
+echo "See: LUMENFLOW.md for workflow details" >&2
+echo "======================" >&2
+exit 2
+`;
+    /* eslint-enable no-useless-escape */
+}
+//# sourceMappingURL=require-wu.js.map

package/dist/hooks/generators/require-wu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"require-wu.js","sourceRoot":"","sources":["../../../src/hooks/generators/require-wu.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB;IACrC,sFAAsF;IACtF,sCAAsC;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+FR,CAAC;IACA,qCAAqC;AACvC,CAAC"}

package/dist/hooks/generators/session-start-recovery.js

@@ -0,0 +1,103 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/session-start-recovery.ts
+ * Generate the session-start-recovery.sh hook script content (WU-1394).
+ *
+ * Extracted from enforcement-generator.ts by WU-1645.
+ */
+/**
+ * Generate the session-start-recovery.sh hook script content.
+ *
+ * This SessionStart hook checks for pending recovery files written by
+ * pre-compact-checkpoint.sh and displays the recovery context to the agent.
+ * After displaying, the recovery file is deleted (one-time recovery).
+ *
+ * Part of WU-1394: Durable recovery pattern for context preservation.
+ */
+export function generateSessionStartRecoveryScript() {
+    // Note: Shell variable escapes (\$, \") are intentional for the generated bash script
+    /* eslint-disable no-useless-escape */
+    return `#!/bin/bash
+#
+# session-start-recovery.sh
+#
+# SessionStart hook - check for pending recovery and inject context (WU-1390)
+#
+# Fires after session start (on compact, resume, or clear) to:
+# 1. Check for recovery-pending-*.md files written by pre-compact-checkpoint.sh
+# 2. Display the recovery context to the agent
+# 3. Remove the recovery file (one-time recovery)
+#
+# This completes the durable recovery pattern:
+#   PreCompact writes file → SessionStart reads and deletes it
+#
+# Exit codes:
+#   0 = Always allow (informational hook)
+#
+
+set -euo pipefail
+
+# Derive repo paths from CLAUDE_PROJECT_DIR
+if [[ -n "\${CLAUDE_PROJECT_DIR:-}" ]]; then
+  REPO_PATH="\$CLAUDE_PROJECT_DIR"
+else
+  REPO_PATH=\$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+  if [[ -z "\$REPO_PATH" ]]; then
+    exit 0
+  fi
+fi
+
+RECOVERY_DIR="\${REPO_PATH}/.lumenflow/state"
+
+# Check if recovery directory exists
+if [[ ! -d "\$RECOVERY_DIR" ]]; then
+  exit 0
+fi
+
+# Find UnsafeAny pending recovery files
+FOUND_RECOVERY=false
+
+for recovery_file in "\$RECOVERY_DIR"/recovery-pending-*.md; do
+  # Check if glob matched UnsafeAny files (bash glob returns literal pattern if no match)
+  [[ -f "\$recovery_file" ]] || continue
+
+  FOUND_RECOVERY=true
+
+  # Extract WU ID from filename for display
+  WU_ID=\$(basename "\$recovery_file" | sed 's/recovery-pending-\\(.*\\)\\.md/\\1/')
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "⚠️  POST-COMPACTION RECOVERY DETECTED" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Display the recovery context
+  cat "\$recovery_file" >&2
+
+  echo "" >&2
+  echo "═══════════════════════════════════════════════════════" >&2
+  echo "" >&2
+
+  # Remove after displaying (one-time recovery)
+  rm -f "\$recovery_file"
+done
+
+# Additional context if recovery was displayed
+if [[ "\$FOUND_RECOVERY" == "true" ]]; then
+  echo "IMPORTANT: Your context was compacted. Review the recovery info above." >&2
+  echo "Recommended: Run 'pnpm wu:brief --id \$WU_ID --client \${LUMENFLOW_CLIENT:-claude-code}' for fresh full context." >&2
+  echo "" >&2
+fi
+
+# WU-1473: Surface unread coordination signals for non-worktree orchestrators
+# Even without recovery files, agents benefit from seeing recent inbox activity
+# This supports orchestrators running from main checkout (not in a worktree)
+pnpm mem:inbox --since 1h --unread-only --quiet 2>/dev/null >&2 || true
+
+exit 0
+`;
+    /* eslint-enable no-useless-escape */
+}
+//# sourceMappingURL=session-start-recovery.js.map

package/dist/hooks/generators/session-start-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-start-recovery.js","sourceRoot":"","sources":["../../../src/hooks/generators/session-start-recovery.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,kCAAkC;IAChD,sFAAsF;IACtF,sCAAsC;IACtC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+ER,CAAC;IACA,qCAAqC;AACvC,CAAC"}

package/dist/hooks/generators/signal-utils.js

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * @file generators/signal-utils.ts
+ * Signal surfacing and marking utilities for enforcement hooks (WU-1473).
+ *
+ * Extracted from enforcement-generator.ts by WU-1645.
+ */
+import { loadSignals, markSignalsAsRead } from '@lumenflow/memory/signal';
+/**
+ * WU-1473: Surface unread signals for agent consumption during claim/start.
+ *
+ * Loads all unread signals from the memory layer and returns them for display.
+ * Implements fail-open: UnsafeAny error returns an empty result without throwing.
+ *
+ * @param baseDir - Project base directory
+ * @returns Unread signal summary (never throws)
+ */
+export async function surfaceUnreadSignals(baseDir) {
+    try {
+        const signals = await loadSignals(baseDir, { unreadOnly: true });
+        return { count: signals.length, signals };
+    }
+    catch {
+        // WU-1473 AC4: Fail-open - memory errors never block lifecycle commands
+        return { count: 0, signals: [] };
+    }
+}
+/**
+ * WU-1473: Mark all signals for a completed WU as read using receipt-aware behavior.
+ *
+ * Loads signals scoped to the given WU ID and marks UnsafeAny unread ones as read
+ * by appending receipts (WU-1472 pattern). Does not rewrite signals.jsonl.
+ * Implements fail-open: UnsafeAny error returns zero count without throwing.
+ *
+ * @param baseDir - Project base directory
+ * @param wuId - WU ID whose signals should be marked as read
+ * @returns Result with count of signals marked (never throws)
+ */
+export async function markCompletedWUSignalsAsRead(baseDir, wuId) {
+    try {
+        const signals = await loadSignals(baseDir, { wuId, unreadOnly: true });
+        if (signals.length === 0) {
+            return { markedCount: 0 };
+        }
+        const signalIds = signals.map((sig) => sig.id);
+        return await markSignalsAsRead(baseDir, signalIds);
+    }
+    catch {
+        // WU-1473 AC4: Fail-open - memory errors never block lifecycle commands
+        return { markedCount: 0 };
+    }
+}
+//# sourceMappingURL=signal-utils.js.map

package/dist/hooks/generators/signal-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-utils.js","sourceRoot":"","sources":["../../../src/hooks/generators/signal-utils.ts"],"names":[],"mappings":"AAAA,iCAAiC;AACjC,yCAAyC;AAEzC;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAyB1E;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,OAAe;IACxD,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACjE,OAAO,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,OAAO,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnC,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,4BAA4B,CAChD,OAAe,EACf,IAAY;IAEZ,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QACvE,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;QAC5B,CAAC;QACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAC/C,OAAO,MAAM,iBAAiB,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IACrD,CAAC;IAAC,MAAM,CAAC;QACP,wEAAwE;QACxE,OAAO,EAAE,WAAW,EAAE,CAAC,EAAE,CAAC;IAC5B,CAAC;AACH,CAAC"}