agileflow 2.94.0 → 2.95.0

package/scripts/archive-completed-stories.sh

@@ -105,13 +105,87 @@ echo -e "${BLUE}Cutoff date: $CUTOFF_DATE${NC}"
 
 # Archive using Node.js (more reliable for JSON manipulation)
 if command -v node &> /dev/null; then
-  STATUS_FILE="$STATUS_FILE" ARCHIVE_DIR="$ARCHIVE_DIR" CUTOFF_DATE="$CUTOFF_DATE" node <<'EOF'
+  STATUS_FILE="$STATUS_FILE" ARCHIVE_DIR="$ARCHIVE_DIR" CUTOFF_DATE="$CUTOFF_DATE" PROJECT_ROOT="$PROJECT_ROOT" node <<'EOF'
 const fs = require('fs');
 const path = require('path');
 
 const statusFile = process.env.STATUS_FILE;
 const archiveDir = process.env.ARCHIVE_DIR;
 const cutoffDate = process.env.CUTOFF_DATE;
+const projectRoot = process.env.PROJECT_ROOT;
+
+// =============================================================================
+// Security: Inline validatePath equivalent (US-0188)
+// =============================================================================
+
+/**
+ * Validate a path is safe and within the base directory.
+ * Rejects direct symlinks within the path but allows symlinked parent directories
+ * (needed for git worktrees where docs/ is often symlinked).
+ * @param {string} inputPath - Path to validate
+ * @param {string} baseDir - Allowed base directory
+ * @returns {{ ok: boolean, resolvedPath?: string, realPath?: string, error?: string }}
+ */
+function validatePath(inputPath, baseDir) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { ok: false, error: 'Path is required and must be a string' };
+  }
+  if (!baseDir || typeof baseDir !== 'string') {
+    return { ok: false, error: 'Base directory is required' };
+  }
+
+  // Resolve to absolute path
+  const resolvedPath = path.resolve(baseDir, inputPath);
+  const resolvedBase = path.resolve(baseDir);
+
+  // Check path stays within base directory (path traversal prevention)
+  if (!resolvedPath.startsWith(resolvedBase + path.sep) && resolvedPath !== resolvedBase) {
+    return { ok: false, error: `Path traversal detected: ${inputPath} escapes ${baseDir}` };
+  }
+
+  // Check if the final target path itself is a symlink (allowSymlinks: false for target)
+  // Note: We allow parent directories to be symlinks (needed for git worktrees)
+  try {
+    const stats = fs.lstatSync(resolvedPath);
+    if (stats.isSymbolicLink()) {
+      // The actual file/directory we're writing to is a symlink - reject
+      return { ok: false, error: `Target path is a symlink: ${resolvedPath}` };
+    }
+  } catch (e) {
+    // Path doesn't exist yet, that's OK for new files
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: `Cannot stat path: ${e.message}` };
+    }
+  }
+
+  // Use fs.realpathSync() to get the actual path after symlink resolution
+  let realPath = resolvedPath;
+  try {
+    realPath = fs.realpathSync(resolvedPath);
+    // We don't restrict realPath to baseDir because parent directories may be
+    // symlinked (e.g., git worktrees). The key protection is:
+    // 1. path.resolve() prevents ../../ traversal in the input
+    // 2. lstatSync() above prevents the target itself from being a symlink
+  } catch (e) {
+    // Path doesn't exist yet, use resolved path
+    if (e.code !== 'ENOENT') {
+      return { ok: false, error: `Cannot resolve real path: ${e.message}` };
+    }
+    realPath = resolvedPath;
+  }
+
+  return { ok: true, resolvedPath, realPath };
+}
+
+// =============================================================================
+// Validate archive directory (US-0188)
+// =============================================================================
+
+const archiveDirValidation = validatePath(archiveDir, projectRoot);
+if (!archiveDirValidation.ok) {
+  console.error(`\x1b[31mSecurity: ${archiveDirValidation.error}. Aborting.\x1b[0m`);
+  process.exit(1);
+}
 
 // Read status.json
 const status = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
@@ -146,7 +220,7 @@ for (const [storyId, story] of Object.entries(toArchive)) {
   const date = new Date(story.completed_at);
   const monthKey = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
 
-  // Security: Validate monthKey matches expected format (YYYY-MM) to prevent path traversal
+  // Security: Validate monthKey matches expected format (YYYY-MM) to prevent path traversal (US-0188 AC)
   if (!/^\d{4}-\d{2}$/.test(monthKey)) {
     console.error(`\x1b[31mSkipping story ${storyId}: invalid date format\x1b[0m`);
     continue;
@@ -165,27 +239,28 @@ for (const [storyId, story] of Object.entries(toArchive)) {
 
 // Write archive files
 for (const [monthKey, archiveData] of Object.entries(byMonth)) {
-  const archiveFile = path.join(archiveDir, `${monthKey}.json`);
+  const archiveFile = `${monthKey}.json`;
 
-  // Security: Verify resolved path stays within archive directory
-  const resolvedPath = path.resolve(archiveFile);
-  const resolvedArchiveDir = path.resolve(archiveDir);
-  if (!resolvedPath.startsWith(resolvedArchiveDir + path.sep) && resolvedPath !== resolvedArchiveDir) {
-    console.error(`\x1b[31mSecurity: Archive path ${archiveFile} escapes archive directory. Skipping.\x1b[0m`);
+  // Security: Use validatePath() with allowSymlinks: false (US-0188 AC)
+  const validation = validatePath(archiveFile, archiveDir);
+  if (!validation.ok) {
+    console.error(`\x1b[31mSecurity: ${validation.error}. Skipping ${monthKey}.\x1b[0m`);
     continue;
   }
 
+  const finalPath = validation.resolvedPath;
+
   // Merge with existing archive if it exists
-  if (fs.existsSync(archiveFile)) {
+  if (fs.existsSync(finalPath)) {
     try {
-      const existing = JSON.parse(fs.readFileSync(archiveFile, 'utf8'));
+      const existing = JSON.parse(fs.readFileSync(finalPath, 'utf8'));
       archiveData.stories = { ...existing.stories, ...archiveData.stories };
     } catch (e) {
       console.error(`\x1b[31mWarning: Could not parse existing ${monthKey}.json, will overwrite\x1b[0m`);
     }
   }
 
-  fs.writeFileSync(archiveFile, JSON.stringify(archiveData, null, 2));
+  fs.writeFileSync(finalPath, JSON.stringify(archiveData, null, 2));
   const count = Object.keys(archiveData.stories).length;
   console.log(`\x1b[32m✓ Archived ${count} stories to ${monthKey}.json\x1b[0m`);
 }

package/scripts/babysit-context-restore.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * babysit-context-restore.js - UserPromptSubmit hook
+ *
+ * Backup mechanism to restore babysit context after plan mode clears context.
+ * When user selects "Clear context and bypass permissions" after ExitPlanMode,
+ * this hook fires on the next user prompt and reminds Claude of babysit rules.
+ *
+ * The primary mechanism is embedding rules in the plan file (Rule #6).
+ * This hook is a backup for edge cases where plan file approach might miss.
+ *
+ * Usage: Called automatically as UserPromptSubmit hook
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Find session-state.json - try multiple locations
+function findSessionState() {
+  const locations = [
+    'docs/09-agents/session-state.json',
+    path.join(process.env.CLAUDE_PROJECT_DIR || '.', 'docs/09-agents/session-state.json'),
+  ];
+
+  for (const loc of locations) {
+    if (fs.existsSync(loc)) {
+      return loc;
+    }
+  }
+  return null;
+}
+
+function main() {
+  const sessionStatePath = findSessionState();
+  if (!sessionStatePath) return;
+
+  try {
+    const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
+
+    // Check if restoration is pending
+    if (!state.babysit_pending_restore) return;
+
+    // Output restoration context
+    console.log('');
+    console.log('\x1b[36m╔══════════════════════════════════════════════════════════════╗\x1b[0m');
+    console.log(
+      '\x1b[36m║\x1b[0m  \x1b[1m\x1b[33m/babysit CONTEXT RESTORED\x1b[0m                                   \x1b[36m║\x1b[0m'
+    );
+    console.log('\x1b[36m╠══════════════════════════════════════════════════════════════╣\x1b[0m');
+    console.log(
+      '\x1b[36m║\x1b[0m  /agileflow:babysit was active before context clear.         \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  These rules are MANDATORY:                                  \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m                                                              \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  1. ALWAYS end responses with AskUserQuestion tool           \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  2. Use EnterPlanMode before non-trivial tasks               \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  3. Delegate complex work to domain experts                  \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  4. Track progress with TodoWrite for 3+ step tasks          \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m                                                              \x1b[36m║\x1b[0m'
+    );
+    console.log(
+      '\x1b[36m║\x1b[0m  For full context: /agileflow:babysit                        \x1b[36m║\x1b[0m'
+    );
+    console.log('\x1b[36m╚══════════════════════════════════════════════════════════════╝\x1b[0m');
+    console.log('');
+
+    // Clear the flag (one-time restoration)
+    state.babysit_pending_restore = false;
+    state.babysit_restored_at = new Date().toISOString();
+    fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+  } catch (e) {
+    // Silently fail - don't break user's workflow
+  }
+}
+
+main();

package/scripts/claude-tmux.sh

@@ -5,28 +5,125 @@
 #   ./claude-tmux.sh              # Start in tmux with default session
 #   ./claude-tmux.sh --no-tmux    # Start without tmux (regular claude)
 #   ./claude-tmux.sh -n           # Same as --no-tmux
+#   ./claude-tmux.sh --rescue     # Kill frozen session and restart fresh
+#   ./claude-tmux.sh --kill       # Kill existing session completely
+#   ./claude-tmux.sh --help       # Show help with keybinds
 #
 # When already in tmux: Just runs claude normally
 # When not in tmux: Creates a tmux session and runs claude inside it
+#
+# FREEZE RECOVERY:
+#   If Claude freezes inside tmux, use these keybinds:
+#   - Alt+k     Send Ctrl+C twice (soft interrupt)
+#   - Alt+K     Force kill the pane immediately
+#   - Alt+R     Respawn pane with fresh shell
+#   - Alt+q     Detach from tmux (session stays alive)
 
 set -e
 
-# Check for --no-tmux flag
+# Parse arguments
 NO_TMUX=false
+RESCUE=false
+KILL_SESSION=false
+SHOW_HELP=false
+
 for arg in "$@"; do
   case $arg in
     --no-tmux|-n)
       NO_TMUX=true
       shift
       ;;
+    --rescue|-r)
+      RESCUE=true
+      shift
+      ;;
+    --kill)
+      KILL_SESSION=true
+      shift
+      ;;
+    --help|-h)
+      SHOW_HELP=true
+      shift
+      ;;
   esac
 done
 
+# Show help
+if [ "$SHOW_HELP" = true ]; then
+  cat << 'EOF'
+AgileFlow Claude tmux Wrapper
+
+USAGE:
+  af [options] [claude-args...]
+  agileflow [options] [claude-args...]
+
+OPTIONS:
+  --no-tmux, -n    Run claude without tmux
+  --rescue, -r     Kill frozen session and restart fresh
+  --kill           Kill existing session completely
+  --help, -h       Show this help
+
+TMUX KEYBINDS:
+  Alt+1-9          Switch to window N
+  Alt+c            Create new window
+  Alt+n/p          Next/previous window
+  Alt+d            Split horizontally
+  Alt+s            Split vertically
+  Alt+arrows       Navigate panes
+  Alt+z            Zoom/unzoom pane
+  Alt+[            Enter copy mode (scroll)
+  Alt+r            Rename window
+  Alt+x            Close pane
+  Alt+w            Close window
+  Alt+q            Detach from tmux
+
+FREEZE RECOVERY:
+  Alt+k            Send Ctrl+C twice (soft interrupt)
+  Alt+K            Force kill pane immediately
+  Alt+R            Respawn pane with fresh shell
+
+If Claude is completely frozen and keybinds don't work:
+  1. Open a new terminal
+  2. Run: af --rescue   (kills and restarts)
+  3. Or:  af --kill     (just kills, doesn't restart)
+EOF
+  exit 0
+fi
+
 # If --no-tmux was specified, just run claude directly
 if [ "$NO_TMUX" = true ]; then
   exec claude "$@"
 fi
 
+# Generate session name based on current directory (needed for rescue/kill)
+DIR_NAME=$(basename "$(pwd)")
+SESSION_NAME="claude-${DIR_NAME}"
+
+# Handle --kill flag
+if [ "$KILL_SESSION" = true ]; then
+  if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+    echo "Killing session: $SESSION_NAME"
+    tmux kill-session -t "$SESSION_NAME"
+    echo "Session killed."
+  else
+    echo "No session named '$SESSION_NAME' found."
+  fi
+  exit 0
+fi
+
+# Handle --rescue flag (kill and restart)
+if [ "$RESCUE" = true ]; then
+  if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
+    echo "Killing frozen session: $SESSION_NAME"
+    tmux kill-session -t "$SESSION_NAME"
+    echo "Session killed. Restarting..."
+    sleep 0.5
+  else
+    echo "No existing session to rescue. Starting fresh..."
+  fi
+  # Continue to create new session below
+fi
+
 # Check if tmux auto-spawn is disabled in config
 METADATA_FILE="docs/00-meta/agileflow-metadata.json"
 if [ -f "$METADATA_FILE" ]; then
@@ -62,9 +159,7 @@ if ! command -v tmux &> /dev/null; then
   exec claude "$@"
 fi
 
-# Generate session name based on current directory
-DIR_NAME=$(basename "$(pwd)")
-SESSION_NAME="claude-${DIR_NAME}"
+# SESSION_NAME already generated above (needed for --rescue and --kill)
 
 # Check if session already exists
 if tmux has-session -t "$SESSION_NAME" 2>/dev/null; then
@@ -78,18 +173,102 @@ echo "Starting Claude in tmux session: $SESSION_NAME"
 # Create session in detached mode first
 tmux new-session -d -s "$SESSION_NAME" -n "main"
 
-# Minimal config - mouse and scrolling only, no fancy styling
+# ══════════════════════════════════════════════════════════════════════════════
+# TMUX CONFIGURATION - Modern status bar with keybinds
+# ══════════════════════════════════════════════════════════════════════════════
+
+# Enable mouse support
 tmux set-option -t "$SESSION_NAME" mouse on
 
 # Fix colors - proper terminal support
 tmux set-option -t "$SESSION_NAME" default-terminal "xterm-256color"
+tmux set-option -t "$SESSION_NAME" -ga terminal-overrides ",xterm-256color:Tc"
+
+# ─── Status Bar Styling (2-line) ──────────────────────────────────────────────
+
+# Status bar position and refresh
+tmux set-option -t "$SESSION_NAME" status-position bottom
+tmux set-option -t "$SESSION_NAME" status-interval 5
+
+# Enable 2-line status bar
+tmux set-option -t "$SESSION_NAME" status 2
+
+# Base styling - Tokyo Night inspired dark theme
+tmux set-option -t "$SESSION_NAME" status-style "bg=#1a1b26,fg=#a9b1d6"
+
+# Line 0 (top): Session name (stripped of claude- prefix) + Keybinds + Git branch
+# Shows freeze recovery keys: Alt+k (soft kill), Alt+K (hard kill)
+tmux set-option -t "$SESSION_NAME" status-format[0] "#[bg=#1a1b26]  #[fg=#e8683a bold]#{s/claude-//:session_name}  #[fg=#3b4261]·  #[fg=#7aa2f7]󰘬 #(git branch --show-current 2>/dev/null || echo '-')  #[align=right]#[fg=#7a7e8a]Alt+k freeze  Alt+x close  Alt+q detach  "
+
+# Line 1 (bottom): Window tabs with smart truncation and brand color
+# - Active window: full name (max 15 chars), brand orange highlight
+# - Inactive windows: truncate to 8 chars with ... suffix, warm gray
+tmux set-option -t "$SESSION_NAME" status-format[1] "#[bg=#1a1b26]#{W:#{?window_active,#[fg=#1a1b26 bg=#e8683a bold]  #I  #[fg=#e8683a bg=#2d2f3a]#[fg=#e0e0e0] #{=15:window_name} #[bg=#1a1b26 fg=#2d2f3a],#[fg=#8a8a8a]  #I:#{=|8|...:window_name}  }}"
 
-# Keybindings: Alt+number to switch windows, Alt+q to detach
+# Pane border styling - blue inactive, orange active
+tmux set-option -t "$SESSION_NAME" pane-border-style "fg=#3d59a1"
+tmux set-option -t "$SESSION_NAME" pane-active-border-style "fg=#e8683a"
+
+# Message styling - orange highlight
+tmux set-option -t "$SESSION_NAME" message-style "bg=#e8683a,fg=#1a1b26,bold"
+
+# ─── Keybindings ──────────────────────────────────────────────────────────────
+
+# Window numbering starts at 1 (not 0)
+tmux set-option -t "$SESSION_NAME" base-index 1
+
+# Alt+number to switch windows (1-9)
 for i in 1 2 3 4 5 6 7 8 9; do
-  tmux bind-key -n "M-$i" select-window -t ":$((i-1))"
+  tmux bind-key -n "M-$i" select-window -t ":$i"
 done
+
+# Alt+c to create new window
+tmux bind-key -n M-c new-window -c "#{pane_current_path}"
+
+# Alt+q to detach
 tmux bind-key -n M-q detach-client
 
+# Alt+d to split horizontally (side by side)
+tmux bind-key -n M-d split-window -h -c "#{pane_current_path}"
+
+# Alt+s to split vertically (top/bottom)
+tmux bind-key -n M-s split-window -v -c "#{pane_current_path}"
+
+# Alt+arrow to navigate panes
+tmux bind-key -n M-Left select-pane -L
+tmux bind-key -n M-Right select-pane -R
+tmux bind-key -n M-Up select-pane -U
+tmux bind-key -n M-Down select-pane -D
+
+# Alt+x to close current pane (with confirmation)
+tmux bind-key -n M-x confirm-before -p "Close pane? (y/n)" kill-pane
+
+# Alt+w to close current window (with confirmation)
+tmux bind-key -n M-w confirm-before -p "Close window? (y/n)" kill-window
+
+# Alt+n/p for next/previous window
+tmux bind-key -n M-n next-window
+tmux bind-key -n M-p previous-window
+
+# Alt+r to rename window
+tmux bind-key -n M-r command-prompt -I "#W" "rename-window '%%'"
+
+# Alt+z to zoom/unzoom pane (fullscreen toggle)
+tmux bind-key -n M-z resize-pane -Z
+
+# Alt+[ to enter copy mode (for scrolling)
+tmux bind-key -n M-[ copy-mode
+
+# ─── Freeze Recovery Keybindings ─────────────────────────────────────────────
+# Alt+k to send Ctrl+C twice (soft interrupt for frozen processes)
+tmux bind-key -n M-k run-shell "tmux send-keys C-c; sleep 0.5; tmux send-keys C-c"
+
+# Alt+K (shift+k) to force-kill pane immediately (nuclear option for hard freezes)
+tmux bind-key -n M-K kill-pane
+
+# Alt+R (shift+r) to respawn the pane (restart with a fresh shell)
+tmux bind-key -n M-R respawn-pane -k
+
 # Send the claude command to the first window
 CLAUDE_CMD="claude"
 if [ $# -gt 0 ]; then