@thebassclef/lite 1.9.16 → 1.9.19

package/dist/lite/lib/prose-marker.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# tier: lite
+#
+# lib/prose-marker.sh — shared marker write + read helpers for the bassclef
+# prose scorer stack. Pins the marker format from
+# standards/prose-marker-format.md v1.0.
+#
+# Producers (Stop hooks that score prose dimensions):
+#   - turn-prose-density-measure.sh (Step 2b of Longrun 2)
+#   - turn-prose-kiss-check.sh      (Step 2c extension)
+#   - turn-prose-grade-measure.sh   (future retrofit; writes raw today)
+#
+# Consumer (UserPromptSubmit hook that reads markers + injects numbers):
+#   - plain-english-steering.sh     (Step 2d extension)
+#
+# Per @luminary john-ousterhout — deep module hides JSON shape + atomic
+# write + expiry logic behind a narrow two-function interface.
+# Per @luminary tony-hoare — pre/postcondition contract per
+# standards/prose-marker-format.md §Hoare.
+# Per @luminary michael-nygard — fail-soft on write permission denied.
+
+set +e
+
+# === BASSCLEF_STATE_ROOT resolution ===
+# When tests isolate state via BASSCLEF_STATE_ROOT env var, honor it.
+# Otherwise resolve to the repo root (walk up from this file's location).
+_prose_marker_resolve_state_root() {
+  if [ -n "${BASSCLEF_STATE_ROOT:-}" ]; then
+    echo "$BASSCLEF_STATE_ROOT"
+    return
+  fi
+  local script_dir
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  echo "$(cd "$script_dir/.." && pwd)"
+}
+
+# === write_prose_marker <scorer-name> <value> [notes] ===
+# Preconditions:
+#   - scorer-name is non-empty and matches [a-z0-9-]+
+#   - value is non-empty
+# Postconditions:
+#   - file at state/markers/<scorer-name>/last-turn.json exists
+#   - JSON matches standards/prose-marker-format.md shape
+#   - atomic write (temp file + mv)
+# Returns: 0 on success; 1 on invalid input; 2 on write failure (fail-soft).
+write_prose_marker() {
+  local scorer="$1"
+  local value="$2"
+  local notes="${3:-}"
+
+  # Validate scorer-name
+  if [ -z "$scorer" ]; then
+    return 1
+  fi
+  if ! echo "$scorer" | grep -qE '^[a-z0-9-]+$'; then
+    return 1
+  fi
+
+  # Validate value
+  if [ -z "$value" ]; then
+    return 1
+  fi
+
+  local state_root
+  state_root="$(_prose_marker_resolve_state_root)"
+  local marker_dir="${state_root}/state/markers/${scorer}"
+  local marker_path="${marker_dir}/last-turn.json"
+
+  if ! mkdir -p "$marker_dir" 2>/dev/null; then
+    return 2
+  fi
+
+  local timestamp
+  timestamp="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  local tmp
+  tmp="$(mktemp "${marker_dir}/last-turn.XXXXXX.tmp" 2>/dev/null)" || return 2
+
+  # Build JSON. Use jq when available for proper escaping; fall back to raw.
+  if command -v jq >/dev/null 2>&1; then
+    if [ -n "$notes" ]; then
+      jq -n \
+        --arg metric "$scorer" \
+        --argjson value "$value" \
+        --arg measured_at "$timestamp" \
+        --arg source "lib/prose-marker.sh" \
+        --arg notes "$notes" \
+        '{metric: $metric, value: $value, measured_at: $measured_at, source: $source, notes: $notes}' \
+        > "$tmp" 2>/dev/null
+    else
+      jq -n \
+        --arg metric "$scorer" \
+        --argjson value "$value" \
+        --arg measured_at "$timestamp" \
+        --arg source "lib/prose-marker.sh" \
+        '{metric: $metric, value: $value, measured_at: $measured_at, source: $source}' \
+        > "$tmp" 2>/dev/null
+    fi
+    local rc=$?
+    if [ "$rc" -ne 0 ]; then
+      rm -f "$tmp" 2>/dev/null
+      return 2
+    fi
+  else
+    # Fallback: raw JSON. Scorer + notes get basic escaping (no quotes in input).
+    if [ -n "$notes" ]; then
+      printf '{"metric":"%s","value":%s,"measured_at":"%s","source":"lib/prose-marker.sh","notes":"%s"}\n' \
+        "$scorer" "$value" "$timestamp" "$notes" > "$tmp" 2>/dev/null
+    else
+      printf '{"metric":"%s","value":%s,"measured_at":"%s","source":"lib/prose-marker.sh"}\n' \
+        "$scorer" "$value" "$timestamp" > "$tmp" 2>/dev/null
+    fi
+  fi
+
+  # Atomic rename
+  if ! mv -f "$tmp" "$marker_path" 2>/dev/null; then
+    rm -f "$tmp" 2>/dev/null
+    return 2
+  fi
+  return 0
+}
+
+# === read_prose_markers [--max-age-minutes N] <scorer-name> [<scorer-name> ...] ===
+# Preconditions:
+#   - zero or more scorer-name arguments
+#   - optional --max-age-minutes N (default 10)
+# Postconditions:
+#   - stdout emits one JSON object mapping scorer-name → marker object OR null
+#   - null when: marker missing, older than max-age, or malformed JSON
+#   - fail-soft: never crashes on bad input
+# Returns: 0 always (fail-soft).
+read_prose_markers() {
+  local max_age_min=10
+  local scorers=()
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --max-age-minutes)
+        shift
+        max_age_min="${1:-10}"
+        shift
+        ;;
+      *)
+        scorers+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local state_root
+  state_root="$(_prose_marker_resolve_state_root)"
+
+  # Build JSON object. If jq missing, emit raw.
+  if command -v jq >/dev/null 2>&1; then
+    # Start with empty object
+    local result='{}'
+    local scorer
+    for scorer in "${scorers[@]}"; do
+      local marker_path="${state_root}/state/markers/${scorer}/last-turn.json"
+      local marker_json="null"
+      if [ -f "$marker_path" ]; then
+        # Age check
+        local file_age_sec
+        if stat -f %m "$marker_path" >/dev/null 2>&1; then
+          # BSD stat (macOS)
+          file_age_sec=$(( $(date +%s) - $(stat -f %m "$marker_path") ))
+        else
+          # GNU stat (Linux)
+          file_age_sec=$(( $(date +%s) - $(stat -c %Y "$marker_path") ))
+        fi
+        local max_age_sec=$(( max_age_min * 60 ))
+        if [ "$file_age_sec" -le "$max_age_sec" ]; then
+          # Parse marker — null on malformed JSON
+          marker_json=$(jq -c '.' "$marker_path" 2>/dev/null)
+          if [ -z "$marker_json" ]; then
+            marker_json="null"
+          fi
+        fi
+      fi
+      result=$(echo "$result" | jq --arg k "$scorer" --argjson v "$marker_json" '. + {($k): $v}' 2>/dev/null)
+    done
+    echo "$result"
+  else
+    # Fallback without jq — emit a flat null map
+    printf '{'
+    local first=1
+    local scorer
+    for scorer in "${scorers[@]}"; do
+      if [ "$first" -eq 0 ]; then
+        printf ','
+      fi
+      printf '"%s":null' "$scorer"
+      first=0
+    done
+    printf '}\n'
+  fi
+  return 0
+}
+
+# Export functions when sourced
+export -f write_prose_marker 2>/dev/null
+export -f read_prose_markers 2>/dev/null
+export -f _prose_marker_resolve_state_root 2>/dev/null

package/dist/lite/lib/tier-dependency-audit.sh

@@ -814,37 +814,64 @@ build_reverse_index() {
 walk_graph_bfs_inbound() {
   local seeds_file="$1"
   local rev_index="$2"
-  local visited_file="" queue_file=""
-  visited_file="$(mktemp)"
-  queue_file="$(mktemp)"
-  # shellcheck disable=SC2064
-  trap "rm -f '$visited_file' '$queue_file'" RETURN
 
   if [ ! -s "$seeds_file" ]; then
-    : > "$visited_file"
-    sort -u "$visited_file"
     return 0
   fi
-  cp "$seeds_file" "$queue_file"
 
-  local max_iter=1000 iter=0
-  while [ -s "$queue_file" ] && [ "$iter" -lt "$max_iter" ]; do
-    iter=$((iter + 1))
-    local next_file; next_file="$(mktemp)"
-    while IFS= read -r p; do
-      [ -z "$p" ] && continue
-      if grep -Fxq "$p" "$visited_file" 2>/dev/null; then continue; fi
-      echo "$p" >> "$visited_file"
-      # Look up callers of $p in the reverse index (path is column 1; caller is column 2)
-      awk -F'\t' -v p="$p" '$1 == p { print $2 }' "$rev_index" | while IFS= read -r caller; do
-        [ -n "$caller" ] && echo "$caller" >> "$next_file"
-      done
-    done < "$queue_file"
-    mv "$next_file" "$queue_file"
-    sort -u -o "$queue_file" "$queue_file"
-  done
+  if [ ! -s "$rev_index" ]; then
+    # No edges — output just the seeds, deduped
+    sort -u "$seeds_file"
+    return 0
+  fi
 
-  sort -u "$visited_file"
+  # Single-pass awk: build reverse-index hash during Phase 1 (reading
+  # rev_index), then run BFS entirely in-memory during Phase 2 (reading
+  # seeds_file via END block). Visited set prevents re-visiting; queue
+  # grows as new callers are found.
+  #
+  # Complexity: O(N + M) where N = seeds + M = edges in rev_index.
+  # Prior per-item awk was O(N × M) — unusable at 1.1MB index (ticket
+  # bassclef-upstream#2109 observed 15+ min hang during /release).
+  #
+  # Per @luminary john-ousterhout — deep module: one awk hides BFS.
+  # Per @luminary michael-feathers — behavior pinned by Tier 0 tests
+  # at lib/tests/tier-dependency-audit-inbound.test.sh.
+  awk -F'\t' '
+    # Phase 1: load reverse index into callers map
+    # Each line: <path>\t<caller>; multiple callers per path concatenated
+    # with SUBSEP as the separator (safe since SUBSEP is non-printable).
+    NR == FNR {
+      if (NF >= 2 && $1 != "") {
+        callers[$1] = (callers[$1] == "" ? $2 : callers[$1] SUBSEP $2)
+      }
+      next
+    }
+    # Phase 2: enqueue seeds (file 2)
+    {
+      if ($0 != "" && !($0 in visited)) {
+        queue[++qlen] = $0
+        visited[$0] = 1
+      }
+    }
+    # Phase 3: BFS, draining the queue
+    END {
+      head = 1
+      while (head <= qlen) {
+        p = queue[head++]
+        if (p in callers) {
+          n = split(callers[p], c, SUBSEP)
+          for (i = 1; i <= n; i++) {
+            if (c[i] != "" && !(c[i] in visited)) {
+              visited[c[i]] = 1
+              queue[++qlen] = c[i]
+            }
+          }
+        }
+      }
+      for (p in visited) print p
+    }
+  ' "$rev_index" "$seeds_file" | sort -u
   return 0
 }
 

package/dist/lite/presence/install/bassclef-sync.template.sh

@@ -256,6 +256,64 @@ bassclef_sync_parse_whereami_ts() {
   return 0
 }
 
+# === #2130 — scope-aware install-class resolution + prior-sync check ===
+# Reads a hook source file's `# install-class:` header. Returns one of:
+#   project | operator | dual | unknown
+# Fails soft — missing file, missing header, or invalid value → "unknown".
+#
+# Anchor luminaries — @luminary linus-torvalds (adopter contract; project-class
+# hooks must not report scope=operator), @luminary jerome-saltzer-and-michael-schroeder
+# (every scope mediated per source declaration), @luminary michael-feathers
+# (characterization anchor — pin the install-class header shape before cure).
+_template_resolve_install_class() {
+  local hook_src="$1"
+  if [ ! -f "$hook_src" ]; then
+    echo "unknown"
+    return 0
+  fi
+  local header_val
+  header_val=$(head -10 "$hook_src" 2>/dev/null | grep -E \
+    '^# install-class:[[:space:]]*(operator|project|dual)[[:space:]]*$' \
+    | head -1 | sed -E 's/^# install-class:[[:space:]]*//;s/[[:space:]]*$//')
+  case "$header_val" in
+    project|operator|dual) echo "$header_val" ;;
+    *) echo "unknown" ;;
+  esac
+}
+
+# Returns 0 (true) if the hook is installed at the scope its install-class names.
+# For `dual`, either project or operator location satisfies.
+# For `unknown`, defaults to operator check per ADR-058 C2 grace window.
+#
+# $1 — hook basename (e.g., "pre-commit-gate.sh")
+# $2 — scope value (project | operator | dual | unknown)
+# Reads $CWD and $HOME. $CWD falls back to $(pwd) when unset.
+_template_hook_present_at_scope() {
+  local hook_name="$1"
+  local scope="$2"
+  local cwd="${CWD:-$(pwd)}"
+  case "$scope" in
+    project)
+      [ -f "$cwd/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    operator)
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    dual)
+      [ -f "$cwd/.claude/hooks/$hook_name" ] && return 0
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+    *)
+      # unknown — grace-window; check operator per legacy behavior
+      [ -f "$HOME/.claude/hooks/$hook_name" ] && return 0
+      return 1
+      ;;
+  esac
+}
+
 # === #1929 — postcondition emitter (RESTORED/DEGRADED + JSON) ===
 # Mirrors .claude/hooks/bassclef-sync.sh L215-243 (idempotent-complete-or-fail-loud
 # pattern shipped under #1894 Cure 1 of #1691). Reads globals INSTALLED_COUNT,
@@ -1022,9 +1080,16 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       fi
       if [ -n "$_WALKER_MISS" ]; then
         echo "$(date -u +%FT%TZ) install-fail-missing-dep $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
-        FAILED_COUNT=$((FAILED_COUNT + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — resolve install-class scope + check if hook is already present
+        # at scoped target from a prior sync. Prior-sync-present counts as installed.
+        _HOOK_SCOPE=$(_template_resolve_install_class "$HOOK_SRC")
+        if _template_hook_present_at_scope "$HOOK_NAME" "$_HOOK_SCOPE"; then
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+        else
+          FAILED_COUNT=$((FAILED_COUNT + 1))
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("$_HOOK_SCOPE")
+        fi
         continue
       fi
 
@@ -1038,9 +1103,15 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
         cp -p "$HOOK_SRC" "$TARGET_USER" 2>/dev/null || true
         chmod +x "$TARGET_USER" 2>/dev/null || true
         echo "$(date -u +%FT%TZ) dispatch-fail $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
-        FAILED_COUNT=$((FAILED_COUNT + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — scope-aware missing[] + prior-sync pass-through
+        _HOOK_SCOPE=$(_template_resolve_install_class "$HOOK_SRC")
+        if _template_hook_present_at_scope "$HOOK_NAME" "$_HOOK_SCOPE"; then
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+        else
+          FAILED_COUNT=$((FAILED_COUNT + 1))
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("$_HOOK_SCOPE")
+        fi
       fi
     elif [ "$HAS_HEADER" = "1" ] && [ "$DISPATCH_AVAILABLE" = "0" ]; then
       # S-F1 MED — dispatch lib missing; trace explicitly (not silent)
@@ -1059,8 +1130,15 @@ if [ -d "$BASSCLEF_DIR/.claude/hooks" ]; then
       else
         echo "$(date -u +%FT%TZ) skipped-invalid-header $HOOK_NAME" >> "$BASSCLEF_TRACE_LOG"
         SKIPPED_INVALID=$((SKIPPED_INVALID + 1))
-        missing_paths+=(".claude/hooks/$HOOK_NAME")
-        missing_scopes+=("operator")
+        # #2130 — invalid header → scope resolves to "unknown"; prior-sync still passes
+        if _template_hook_present_at_scope "$HOOK_NAME" "unknown"; then
+          # Operator-scope fallback cp above landed; treat as installed under grace
+          INSTALLED_COUNT=$((INSTALLED_COUNT + 1))
+          SKIPPED_INVALID=$((SKIPPED_INVALID - 1))
+        else
+          missing_paths+=(".claude/hooks/$HOOK_NAME")
+          missing_scopes+=("unknown")
+        fi
       fi
     fi
   done

package/dist/lite/presence/install/schedule-auto-save.cron.sh

@@ -28,8 +28,21 @@
 
 set -euo pipefail
 
-BASSCLEF_HOOK_DEFAULT="$HOME/src/sunj-labs/bassclef/.claude/hooks/auto-save-idle.sh"
-HOOK_PATH="${1:-${BASSCLEF_HOOK_PATH:-$BASSCLEF_HOOK_DEFAULT}}"
+# Hook path resolution — closes bassclef-upstream#2257.
+# Cold adopters do not have $HOME/src/sunj-labs/bassclef cloned; they get
+# the hook installed at $CLAUDE_PROJECT_DIR/.claude/hooks/ via `bassclef init`.
+# Probe adopter project dir first, then dev sibling. Positional arg and
+# BASSCLEF_HOOK_PATH env override still win over the probe.
+_probe_hook_path() {
+  local proj="${CLAUDE_PROJECT_DIR:-}"
+  if [ -n "$proj" ] && [ -f "$proj/.claude/hooks/auto-save-idle.sh" ]; then
+    echo "$proj/.claude/hooks/auto-save-idle.sh"
+    return 0
+  fi
+  echo "$HOME/src/sunj-labs/bassclef/.claude/hooks/auto-save-idle.sh"
+}
+
+HOOK_PATH="${1:-${BASSCLEF_HOOK_PATH:-$(_probe_hook_path)}}"
 CRON_MARKER="# bassclef auto-save (ADR-046)"
 CRON_ENTRY="*/15 * * * * bash ${HOOK_PATH} >/dev/null 2>&1"
 
@@ -54,6 +67,21 @@ fi
 # Check hook file exists
 if [ ! -f "$HOOK_PATH" ]; then
   echo "ERROR: hook file not found at ${HOOK_PATH}"
+  echo ""
+  echo "Resolution order (per bassclef-upstream#2257):"
+  echo "  1. positional arg \$1 — not set"
+  if [ -n "${BASSCLEF_HOOK_PATH:-}" ]; then
+    echo "  2. BASSCLEF_HOOK_PATH env — set to ${BASSCLEF_HOOK_PATH}"
+  else
+    echo "  2. BASSCLEF_HOOK_PATH env — not set"
+  fi
+  if [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+    echo "  3. CLAUDE_PROJECT_DIR probe — tried ${CLAUDE_PROJECT_DIR}/.claude/hooks/auto-save-idle.sh"
+  else
+    echo "  3. CLAUDE_PROJECT_DIR probe — unset; skipped"
+  fi
+  echo "  4. Dev sibling fallback — tried ${HOME}/src/sunj-labs/bassclef/.claude/hooks/auto-save-idle.sh"
+  echo ""
   echo "  Pass the path as an argument OR set BASSCLEF_HOOK_PATH env var."
   echo "  Example: bash $0 /path/to/bassclef/.claude/hooks/auto-save-idle.sh"
   exit 2

package/dist/lite/scripts/generate-lite-manifest.sh

@@ -497,6 +497,18 @@ while IFS= read -r f; do
 done < <(find "$REPO_ROOT/.claude/hooks" -mindepth 2 -type f -name '*.sh' \
            -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
 
+# Skill-helper scripts (bash) — per bassclef-upstream#2140. Skills (e.g.,
+# onboard-repo) dispatch helper .sh files from their SKILL.md Procedure
+# steps. Lite adopters that run those skills need the helpers to land
+# in their bundle. Shipped as type=script (reuses existing enum; no
+# schema shape change). Only lite-tagged helpers end up in lite-manifest;
+# standard-tagged helpers inherit into standard-manifest + above.
+SKILL_HELPER_FILES=()
+while IFS= read -r f; do
+  SKILL_HELPER_FILES+=("$f")
+done < <(find "$REPO_ROOT/.claude/skills" -mindepth 2 -type f -name '*.sh' \
+           -not -path '*/tests/*' -not -path '*/fixtures/*' 2>/dev/null | sort)
+
 # Top-level .claude/*.md (bassclef-orientation.md) — vendored via @import from adopter
 # CLAUDE.md; ships as root-doc. Per goal 2026-09-16a.
 CLAUDE_DOC_FILES=()
@@ -635,6 +647,9 @@ ENTRIES_JSON=$(
     if [[ ${#SCRIPT_FILES[@]} -gt 0 ]]; then
       emit_entries "script"  extract_hook_tier extract_hook_description basename "${SCRIPT_FILES[@]}"
     fi
+    if [[ ${#SKILL_HELPER_FILES[@]} -gt 0 ]]; then
+      emit_entries "script"  extract_hook_tier extract_hook_description basename "${SKILL_HELPER_FILES[@]}"
+    fi
     if [[ ${#PRESENCE_TEMPLATE_SH_FILES[@]} -gt 0 ]]; then
       emit_entries "presence-template" extract_hook_tier extract_hook_description basename "${PRESENCE_TEMPLATE_SH_FILES[@]}"
     fi

package/dist/lite/scripts/launch/local-serve.sh

@@ -30,16 +30,157 @@
 # Cleanup: rely on the operator running scripts/launch/local-serve-stop.sh
 # or just killing the PID. State file lists the PID for reference.
 
-set -e
+# === #2131 — testable helpers for arg parsing + usage ===
+# Anchor luminaries — @luminary linus-torvalds (default bind unchanged;
+# --lan is opt-in; no silent regression), @luminary alan-cooper (honesty
+# default — handoff text matches bind reality), @luminary michael-feathers
+# (characterization anchor via LOCAL_SERVE_TEST_MODE guard).
+
+_local_serve_print_usage() {
+  cat <<'USAGE'
+usage: local-serve.sh [--lan] <gallery-dir> [port-hint]
+
+Serves a /launch local-mode prototype gallery via python http.server.
+
+Positional:
+  gallery-dir   path to the gallery directory (must contain index.html)
+  port-hint     optional starting port (default 8000)
+
+Flags:
+  --lan         bind to 0.0.0.0 (all interfaces) and PRINT the detected
+                LAN IP so phones/iPads on the same Wi-Fi can reach the
+                URL directly. Default is 127.0.0.1 (this computer only).
+                Prints a warning: any device on this Wi-Fi can open the URL.
+                Firewall note: macOS firewall may need to be off for the
+                port, or the OS will prompt on first bind.
+  --help        print this usage
+
+Exit codes:
+  0  — server started OR idempotent re-run returns existing URL
+  1  — python3 missing, gallery dir missing, port exhaustion, server crash
+  2  — bad args (missing gallery-dir, unknown flag)
+USAGE
+}
+
+# Detects the machine's LAN IP so --lan mode can print a dialable URL
+# instead of literal "0.0.0.0". Tries mac first (ipconfig getifaddr en0),
+# then linux (hostname -I | awk '{print $1}'). Returns empty on both
+# failures — the caller falls back to 127.0.0.1 so the --lan path
+# degrades to "this computer only" rather than crashing.
+# Per bassclef-upstream#2143 — the prior shape printed 0.0.0.0 which
+# phones cannot dial.
+_local_serve_detect_lan_ip() {
+  local ip
+  # macOS primary: en0 is the typical Wi-Fi interface
+  if command -v ipconfig >/dev/null 2>&1; then
+    ip=$(ipconfig getifaddr en0 2>/dev/null || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+    # macOS fallback: try en1 (secondary Wi-Fi on some models)
+    ip=$(ipconfig getifaddr en1 2>/dev/null || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+  fi
+  # Linux: hostname -I returns space-separated IPs; first is usually primary LAN
+  if command -v hostname >/dev/null 2>&1; then
+    ip=$(hostname -I 2>/dev/null | awk '{print $1}' || true)
+    if [ -n "$ip" ]; then
+      echo "$ip"
+      return 0
+    fi
+  fi
+  # Fallback: empty — caller uses 127.0.0.1
+  return 0
+}
+
+# Parses CLI args. Sets globals BIND_ADDR, DISPLAY_HOST, LAN_WARNING,
+# GALLERY_DIR_PARSED, PORT_HINT_PARSED. Returns 0 on success. Returns
+# non-zero on --help, unknown flag, or missing gallery-dir.
+#
+# BIND_ADDR is what python's http.server --bind sees (127.0.0.1 default,
+# 0.0.0.0 under --lan so it listens on all interfaces).
+# DISPLAY_HOST is what the printed URL + state file carries (127.0.0.1
+# default, detected LAN IP under --lan). Separate so the printed URL is
+# always dialable: 127.0.0.1 for the host, LAN IP for a phone on the
+# same Wi-Fi. Per bassclef-upstream#2143.
+_local_serve_parse_args() {
+  BIND_ADDR="127.0.0.1"
+  DISPLAY_HOST="127.0.0.1"
+  LAN_WARNING=""
+  GALLERY_DIR_PARSED=""
+  PORT_HINT_PARSED="8000"
+  local positional=()
+  local arg
+  local lan_mode=0
+  for arg in "$@"; do
+    case "$arg" in
+      --lan)
+        lan_mode=1
+        BIND_ADDR="0.0.0.0"
+        LAN_WARNING="WARN: --lan set; any device on this Wi-Fi can open this URL. Unset --lan to bind 127.0.0.1 only."
+        ;;
+      --help|-h)
+        _local_serve_print_usage
+        return 1
+        ;;
+      --*)
+        echo "ERROR: unknown flag: $arg" >&2
+        _local_serve_print_usage >&2
+        return 2
+        ;;
+      *)
+        positional+=("$arg")
+        ;;
+    esac
+  done
+  if [ "$lan_mode" -eq 1 ]; then
+    local detected
+    detected=$(_local_serve_detect_lan_ip)
+    if [ -n "$detected" ]; then
+      DISPLAY_HOST="$detected"
+    else
+      # Detection failed; fall back to 127.0.0.1 so the printed URL is still
+      # dialable from the host at least. Warn so the operator knows the
+      # phone-preview path won't work.
+      DISPLAY_HOST="127.0.0.1"
+      LAN_WARNING="${LAN_WARNING}
+WARN: --lan set but LAN IP detection failed (ipconfig / hostname). Printed URL falls back to 127.0.0.1; phone preview will not work."
+    fi
+  fi
+  if [ "${#positional[@]}" -ge 1 ]; then
+    GALLERY_DIR_PARSED="${positional[0]}"
+  fi
+  if [ "${#positional[@]}" -ge 2 ]; then
+    PORT_HINT_PARSED="${positional[1]}"
+  fi
+  if [ -z "$GALLERY_DIR_PARSED" ]; then
+    echo "ERROR: gallery-dir required" >&2
+    _local_serve_print_usage >&2
+    return 2
+  fi
+  return 0
+}
 
-GALLERY_DIR="${1:-}"
-PORT_HINT="${2:-8000}"
+# === Test-mode guard — tests source + exercise helpers without running main ===
+if [ "${LOCAL_SERVE_TEST_MODE:-}" = "1" ]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+set -e
 
-if [ -z "$GALLERY_DIR" ]; then
-  echo "ERROR: gallery-dir required" >&2
-  echo "usage: $0 <gallery-dir> [port-hint]" >&2
+if ! _local_serve_parse_args "$@"; then
   exit 2
 fi
+GALLERY_DIR="$GALLERY_DIR_PARSED"
+PORT_HINT="$PORT_HINT_PARSED"
+
+if [ -n "$LAN_WARNING" ]; then
+  echo "$LAN_WARNING" >&2
+fi
 
 if ! command -v python3 >/dev/null 2>&1; then
   echo "ERROR: python3 not on PATH. Install python3 first." >&2
@@ -92,7 +233,7 @@ fi
 
 # Start http.server in background, bound to 127.0.0.1 only (no external exposure)
 LOG_FILE="$STATE_DIR/${GALLERY_SLUG}.log"
-nohup python3 -m http.server "$PORT" --bind 127.0.0.1 --directory "$GALLERY_DIR" \
+nohup python3 -m http.server "$PORT" --bind "$BIND_ADDR" --directory "$GALLERY_DIR" \
   > "$LOG_FILE" 2>&1 &
 SERVER_PID=$!
 
@@ -103,7 +244,7 @@ if ! kill -0 "$SERVER_PID" 2>/dev/null; then
   exit 1
 fi
 
-URL="http://127.0.0.1:${PORT}/"
+URL="http://${DISPLAY_HOST}:${PORT}/"
 
 # Write state file
 cat > "$STATE_FILE" <<EOF