work-ally 0.2.0-alpha.1

package/internal/lib/common.sh

@@ -0,0 +1,1450 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+work_ally_append_timeline_log() {
+  local level="$1"
+  shift || true
+  [ -n "${WORK_ALLY_LOG_DIR:-}" ] || return 0
+  mkdir -p "$WORK_ALLY_LOG_DIR" 2>/dev/null || return 0
+
+  local stamp target
+  if [ -n "${WORK_ALLY_TIMEZONE:-}" ]; then
+    stamp=$(TZ="$WORK_ALLY_TIMEZONE" date +%F 2>/dev/null || date +%F)
+  else
+    stamp=$(date +%F)
+  fi
+  target="$WORK_ALLY_LOG_DIR/timeline-$stamp.log"
+  printf '%s [%s] [shell] %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$level" "$*" >> "$target" 2>/dev/null || true
+}
+
+work_ally_note() {
+  printf '→ %s\n' "$*"
+  work_ally_append_timeline_log INFO "$*"
+}
+
+work_ally_ok() {
+  printf '✓ %s\n' "$*"
+  work_ally_append_timeline_log INFO "$*"
+}
+
+work_ally_warn() {
+  printf '⚠ %s\n' "$*" >&2
+  work_ally_append_timeline_log WARN "$*"
+}
+
+work_ally_die() {
+  printf '✗ %s\n' "$*" >&2
+  work_ally_append_timeline_log ERROR "$*"
+  exit 1
+}
+
+work_ally_require_cmd() {
+  command -v "$1" >/dev/null 2>&1 || work_ally_die "$1 is required"
+}
+
+work_ally_is_managed_ai_shell() {
+  if [ "${WORK_ALLY_ALLOW_MANAGED_START:-0}" = "1" ]; then
+    return 1
+  fi
+  if [ -n "${CODEX_THREAD_ID:-}" ]; then
+    return 0
+  fi
+  if [ "${CODEX_CI:-0}" = "1" ]; then
+    return 0
+  fi
+  return 1
+}
+
+work_ally_cmd_name() {
+  printf '%s\n' "${WORK_ALLY_CMD_NAME:-ally.sh}"
+}
+
+work_ally_abs_path() {
+  local target="$1"
+  if [ -d "$target" ]; then
+    (cd "$target" && pwd)
+  else
+    local dir
+    dir=$(cd "$(dirname "$target")" && pwd)
+    printf '%s/%s\n' "$dir" "$(basename "$target")"
+  fi
+}
+
+work_ally_init_context() {
+  export WORK_ALLY_WORKSPACE_ROOT="${WORK_ALLY_WORKSPACE_ROOT:?WORK_ALLY_WORKSPACE_ROOT is required}"
+  export WORK_ALLY_INSTALL_ROOT="${WORK_ALLY_INSTALL_ROOT:-${WORK_ALLY_IMPLEMENTATION_DIR:?WORK_ALLY_IMPLEMENTATION_DIR is required}}"
+  export WORK_ALLY_IMPLEMENTATION_DIR="${WORK_ALLY_IMPLEMENTATION_DIR:?WORK_ALLY_IMPLEMENTATION_DIR is required}"
+  export WORK_ALLY_HOME="${WORK_ALLY_HOME:-$HOME/.work-ally}"
+  export WORK_ALLY_ASSISTANTS_DIR="${WORK_ALLY_ASSISTANTS_DIR:-$WORK_ALLY_HOME/assistants}"
+  export WORK_ALLY_ASSISTANT_REGISTRY_FILE="${WORK_ALLY_ASSISTANT_REGISTRY_FILE:-$WORK_ALLY_ASSISTANTS_DIR/registry.yaml}"
+  export WORK_ALLY_PROJECT_REGISTRY_FILE="${WORK_ALLY_PROJECT_REGISTRY_FILE:-$WORK_ALLY_HOME/projects/registry.yaml}"
+  export WORK_ALLY_IMPLEMENTATION_CACHE_DIR="${WORK_ALLY_IMPLEMENTATION_CACHE_DIR:-$WORK_ALLY_HOME/implementation}"
+  
+  local resolved_workspace
+  resolved_workspace=$(work_ally_resolve_registered_workspace_for_path "$WORK_ALLY_WORKSPACE_ROOT" || true)
+  if [ -n "$resolved_workspace" ]; then
+    export WORK_ALLY_WORKSPACE_ROOT="$resolved_workspace"
+  fi
+
+  if [ -z "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+    WORK_ALLY_ASSISTANT_NAME=$(work_ally_resolve_registered_assistant_for_workspace "$WORK_ALLY_WORKSPACE_ROOT" || true)
+    export WORK_ALLY_ASSISTANT_NAME
+  fi
+
+  if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+    work_ally_hydrate_assistant_context "$WORK_ALLY_ASSISTANT_NAME" || true
+  fi
+}
+
+work_ally_ensure_state_dirs() {
+  mkdir -p \
+    "$WORK_ALLY_HOME" \
+    "$WORK_ALLY_ASSISTANTS_DIR" \
+    "$(dirname "$WORK_ALLY_PROJECT_REGISTRY_FILE")"
+
+  if [ -n "${WORK_ALLY_STATE_DIR:-}" ]; then
+    mkdir -p \
+      "$WORK_ALLY_STATE_DIR" \
+      "$WORK_ALLY_RUNTIME_DIR" \
+      "$WORK_ALLY_LOG_DIR" \
+      "$WORK_ALLY_SESSION_DIR" \
+      "$WORK_ALLY_RUN_DIR" \
+      "$WORK_ALLY_CACHE_DIR"
+  fi
+}
+
+work_ally_validate_assistant_name() {
+  local name="$1"
+  case "$name" in
+    ''|*[!A-Za-z0-9._-]*)
+      work_ally_die "Invalid assistant name: $name"
+      ;;
+  esac
+}
+
+work_ally_assistant_home() {
+  local name="$1"
+  printf '%s/%s\n' "$WORK_ALLY_ASSISTANTS_DIR" "$name"
+}
+
+work_ally_assistant_system_dir() {
+  local name="$1"
+  printf '%s/.system\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_codex_home() {
+  local name="$1"
+  printf '%s/codex-home\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_conversations_dir() {
+  local name="$1"
+  printf '%s/conversations\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_sessions_dir() {
+  local name="$1"
+  printf '%s/sessions\n' "$(work_ally_assistant_runtime_dir "$name")"
+}
+
+work_ally_assistant_archive_dir() {
+  local name="$1"
+  printf '%s/archive\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_journal_dir() {
+  local name="$1"
+  printf '%s/journal\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_daily_memory_dir() {
+  local name="$1"
+  work_ally_assistant_journal_dir "$name"
+}
+
+work_ally_assistant_long_term_memory_dir() {
+  local name="$1"
+  work_ally_assistant_home "$name"
+}
+
+work_ally_assistant_routines_dir() {
+  local name="$1"
+  printf '%s/routines\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_runtime_dir() {
+  local name="$1"
+  printf '%s/runtime\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_logs_dir() {
+  local name="$1"
+  printf '%s/logs\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_runs_dir() {
+  local name="$1"
+  printf '%s/runs\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_cache_dir() {
+  local name="$1"
+  printf '%s/cache\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_env_file() {
+  local name="$1"
+  printf '%s/config.env\n' "$(work_ally_assistant_system_dir "$name")"
+}
+
+work_ally_assistant_state_file() {
+  local name="$1"
+  printf '%s/assistant.env\n' "$(work_ally_assistant_runtime_dir "$name")"
+}
+
+work_ally_assistant_now_file() {
+  local name="$1"
+  printf '%s/NOW.md\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_soul_file() {
+  local name="$1"
+  printf '%s/SOUL.md\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_memory_file() {
+  local name="$1"
+  printf '%s/MEMORY.md\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_assistant_mistakes_file() {
+  local name="$1"
+  printf '%s/MISTAKES.md\n' "$(work_ally_assistant_home "$name")"
+}
+
+work_ally_hydrate_assistant_context() {
+  local name="$1"
+  [ -n "$name" ] || return 1
+  export WORK_ALLY_ASSISTANT_NAME="$name"
+  export WORK_ALLY_ASSISTANT_HOME="$(work_ally_assistant_home "$name")"
+  export WORK_ALLY_STATE_DIR="$(work_ally_assistant_system_dir "$name")"
+  export WORK_ALLY_RUNTIME_DIR="$(work_ally_assistant_runtime_dir "$name")"
+  export WORK_ALLY_LOG_DIR="$(work_ally_assistant_logs_dir "$name")"
+  export WORK_ALLY_SESSION_DIR="$(work_ally_assistant_sessions_dir "$name")"
+  export WORK_ALLY_RUN_DIR="$(work_ally_assistant_runs_dir "$name")"
+  export WORK_ALLY_CACHE_DIR="$(work_ally_assistant_cache_dir "$name")"
+  export WORK_ALLY_ENV_FILE="$(work_ally_assistant_env_file "$name")"
+  export WORK_ALLY_ASSISTANT_STATE_FILE="$(work_ally_assistant_state_file "$name")"
+}
+
+work_ally_project_registry_has_workspace() {
+  local workspace_root="$1"
+  [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ] || return 1
+  grep -Fq "workspace_root: $workspace_root" "$WORK_ALLY_PROJECT_REGISTRY_FILE"
+}
+
+work_ally_project_registry_assistants_for_workspace() {
+  local workspace_root="$1"
+  [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ] || return 1
+  awk -v workspace="$workspace_root" '
+    $0 ~ /^  - workspace_root: / {
+      current = substr($0, length("  - workspace_root: ") + 1)
+      next
+    }
+    current == workspace && $0 ~ /^    assistant: / {
+      value = substr($0, length("    assistant: ") + 1)
+      print value
+    }
+  ' "$WORK_ALLY_PROJECT_REGISTRY_FILE" | awk 'NF && !seen[$0]++ { print }'
+}
+
+work_ally_project_registry_assistant_for_workspace() {
+  local workspace_root="$1"
+  local assistants count
+  assistants=$(work_ally_project_registry_assistants_for_workspace "$workspace_root" || true)
+  count=$(printf '%s\n' "$assistants" | awk 'NF { count += 1 } END { print count + 0 }')
+  if [ "$count" -eq 1 ]; then
+    printf '%s\n' "$assistants" | awk 'NF { print; exit }'
+    return 0
+  fi
+  return 1
+}
+
+work_ally_project_registry_workspace_for_path() {
+  local target_path="$1"
+  [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ] || return 1
+  awk -v target="$target_path" '
+    function matches(workspace, candidate) {
+      return candidate == workspace || index(candidate, workspace "/") == 1
+    }
+    $0 ~ /^  - workspace_root: / {
+      workspace = substr($0, length("  - workspace_root: ") + 1)
+      if (matches(workspace, target) && length(workspace) > best_len) {
+        best = workspace
+        best_len = length(workspace)
+      }
+    }
+    END {
+      if (best_len > 0) {
+        print best
+      }
+    }
+  ' "$WORK_ALLY_PROJECT_REGISTRY_FILE"
+}
+
+work_ally_project_registry_workspace_for_assistant() {
+  local assistant_name="$1"
+  [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ] || return 1
+  awk -v assistant="$assistant_name" '
+    /^  - workspace_root: / {
+      current_workspace = substr($0, length("  - workspace_root: ") + 1)
+      next
+    }
+    $0 == "    assistant: " assistant {
+      print current_workspace
+      exit
+    }
+  ' "$WORK_ALLY_PROJECT_REGISTRY_FILE"
+}
+
+work_ally_project_registry_set() {
+  local workspace_root="$1"
+  local assistant_name="$2"
+  local tmp
+  mkdir -p "$(dirname "$WORK_ALLY_PROJECT_REGISTRY_FILE")"
+  tmp=$(mktemp "${TMPDIR:-/tmp}/work-ally-project-registry.XXXXXX")
+
+  if [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ]; then
+    awk -v assistant="$assistant_name" '
+      BEGIN {
+        block = ""
+        in_block = 0
+        skip = 0
+      }
+      /^  - workspace_root: / {
+        if (in_block && !skip) {
+          printf "%s", block
+        }
+        block = $0 ORS
+        in_block = 1
+        skip = 0
+        next
+      }
+      in_block {
+        block = block $0 ORS
+        if ($0 ~ /^    assistant: /) {
+          current_assistant = substr($0, length("    assistant: ") + 1)
+          if (current_assistant == assistant) {
+            skip = 1
+          }
+        }
+        next
+      }
+      { print }
+      END {
+        if (in_block && !skip) {
+          printf "%s", block
+        }
+      }
+    ' "$WORK_ALLY_PROJECT_REGISTRY_FILE" > "$tmp"
+  else
+    printf 'projects:\n' > "$tmp"
+  fi
+
+  if ! grep -q '^projects:$' "$tmp"; then
+    printf 'projects:\n' | cat - "$tmp" > "$tmp.with-header"
+    mv "$tmp.with-header" "$tmp"
+  fi
+
+  if ! awk -v workspace="$workspace_root" -v assistant="$assistant_name" '
+    $0 ~ /^  - workspace_root: / {
+      current = substr($0, length("  - workspace_root: ") + 1)
+      next
+    }
+    current == workspace && $0 == "    assistant: " assistant {
+      found = 1
+    }
+    END { exit(found ? 0 : 1) }
+  ' "$tmp"; then
+    {
+      printf '  - workspace_root: %s\n' "$workspace_root"
+      printf '    assistant: %s\n' "$assistant_name"
+    } >> "$tmp"
+  fi
+
+  mv "$tmp" "$WORK_ALLY_PROJECT_REGISTRY_FILE"
+}
+
+work_ally_project_registry_remove_assistant() {
+  local assistant_name="$1"
+  local tmp
+  [ -f "$WORK_ALLY_PROJECT_REGISTRY_FILE" ] || return 0
+  tmp=$(mktemp "${TMPDIR:-/tmp}/work-ally-project-registry.XXXXXX")
+
+  awk -v assistant="$assistant_name" '
+    BEGIN {
+      block = ""
+      in_block = 0
+      skip = 0
+    }
+    /^  - workspace_root: / {
+      if (in_block && !skip) {
+        printf "%s", block
+      }
+      block = $0 ORS
+      in_block = 1
+      skip = 0
+      next
+    }
+    in_block {
+      block = block $0 ORS
+      if ($0 ~ /^    assistant: /) {
+        current_assistant = substr($0, length("    assistant: ") + 1)
+        if (current_assistant == assistant) {
+          skip = 1
+        }
+      }
+      next
+    }
+    { print }
+    END {
+      if (in_block && !skip) {
+        printf "%s", block
+      }
+    }
+  ' "$WORK_ALLY_PROJECT_REGISTRY_FILE" > "$tmp"
+
+  if ! grep -q '^projects:$' "$tmp"; then
+    printf 'projects:\n' > "$tmp.with-header"
+    cat "$tmp" >> "$tmp.with-header"
+    mv "$tmp.with-header" "$tmp"
+  fi
+
+  mv "$tmp" "$WORK_ALLY_PROJECT_REGISTRY_FILE"
+}
+
+work_ally_resolve_registered_workspace_for_path() {
+  local workspace_root="${1:-$WORK_ALLY_WORKSPACE_ROOT}"
+  work_ally_project_registry_workspace_for_path "$workspace_root"
+}
+
+work_ally_resolve_registered_assistant_for_workspace() {
+  local workspace_root="${1:-$WORK_ALLY_WORKSPACE_ROOT}"
+  work_ally_project_registry_assistant_for_workspace "$workspace_root"
+}
+
+work_ally_assistant_git_origin_url() {
+  local assistant_home="$1"
+  command -v git >/dev/null 2>&1 || return 0
+  [ -d "$assistant_home/.git" ] || return 0
+  git -C "$assistant_home" remote get-url origin 2>/dev/null || true
+}
+
+work_ally_assistant_git_branch() {
+  local assistant_home="$1"
+  command -v git >/dev/null 2>&1 || {
+    printf 'main\n'
+    return 0
+  }
+
+  local branch
+  branch=$(git -C "$assistant_home" branch --show-current 2>/dev/null || true)
+  printf '%s\n' "${branch:-main}"
+}
+
+work_ally_assistant_git_setup() {
+  local assistant_home="$1"
+  local remote_url="${2:-}"
+
+  if ! command -v git >/dev/null 2>&1; then
+    work_ally_warn "git is unavailable; assistant desk autosave is disabled"
+    return 1
+  fi
+
+  if [ ! -d "$assistant_home/.git" ]; then
+    if ! git -C "$assistant_home" init -b main >/dev/null 2>&1; then
+      git -C "$assistant_home" init >/dev/null 2>&1 || {
+        work_ally_warn "Failed to initialize assistant Git repo at $assistant_home"
+        return 1
+      }
+      git -C "$assistant_home" branch -M main >/dev/null 2>&1 || true
+    fi
+  fi
+
+  git -C "$assistant_home" config user.name work-ally >/dev/null 2>&1 || true
+  git -C "$assistant_home" config user.email work-ally@local >/dev/null 2>&1 || true
+
+  if [ -n "$remote_url" ]; then
+    if git -C "$assistant_home" remote get-url origin >/dev/null 2>&1; then
+      git -C "$assistant_home" remote set-url origin "$remote_url" >/dev/null 2>&1 || {
+        work_ally_warn "Failed to update assistant Git remote for $assistant_home"
+        return 1
+      }
+    else
+      git -C "$assistant_home" remote add origin "$remote_url" >/dev/null 2>&1 || {
+        work_ally_warn "Failed to add assistant Git remote for $assistant_home"
+        return 1
+      }
+    fi
+  fi
+
+  return 0
+}
+
+work_ally_assistant_git_prepare_index() {
+  local assistant_home="$1"
+
+  command -v git >/dev/null 2>&1 || return 0
+  [ -d "$assistant_home/.git" ] || return 0
+
+  git -C "$assistant_home" rm --cached -r --ignore-unmatch     .system/config.env     .system/logs     .system/cache     .system/runtime     .system/runs     .system/codex-home/.personality_migration     .system/codex-home/logs_1.sqlite     .system/codex-home/logs_1.sqlite-shm     .system/codex-home/logs_1.sqlite-wal     .system/codex-home/state_5.sqlite     .system/codex-home/sessions     .system/codex-home/shell_snapshots     .system/codex-home/skills     .system/codex-home/tmp >/dev/null 2>&1 || true
+}
+
+work_ally_assistant_git_checkpoint() {
+  local assistant_home="$1"
+  local reason="${2:-checkpoint}"
+  local branch remote_url stamp
+
+  command -v git >/dev/null 2>&1 || return 0
+  [ -d "$assistant_home/.git" ] || return 0
+
+  work_ally_assistant_git_prepare_index "$assistant_home"
+
+  if ! git -C "$assistant_home" add -A >/dev/null 2>&1; then
+    work_ally_warn "Failed to stage assistant desk changes at $assistant_home"
+    return 1
+  fi
+
+  if git -C "$assistant_home" diff --cached --quiet --ignore-submodules --exit-code >/dev/null 2>&1; then
+    return 0
+  fi
+
+  stamp=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  if ! git -C "$assistant_home" commit -m "work-ally: $reason ($stamp)" >/dev/null 2>&1; then
+    work_ally_warn "Failed to commit assistant desk changes at $assistant_home"
+    return 1
+  fi
+
+  remote_url=$(work_ally_assistant_git_origin_url "$assistant_home")
+  if [ -n "$remote_url" ]; then
+    branch=$(work_ally_assistant_git_branch "$assistant_home")
+    git -C "$assistant_home" push -u origin "$branch" >/dev/null 2>&1 || work_ally_warn "Assistant desk push failed for $assistant_home"
+  fi
+
+  return 0
+}
+
+work_ally_registry_has_assistant() {
+  local name="$1"
+  [ -f "$WORK_ALLY_ASSISTANT_REGISTRY_FILE" ] || return 1
+  grep -Eq "^[[:space:]]{2}${name}:$" "$WORK_ALLY_ASSISTANT_REGISTRY_FILE"
+}
+
+work_ally_registry_field() {
+  local name="$1"
+  local field="$2"
+  [ -f "$WORK_ALLY_ASSISTANT_REGISTRY_FILE" ] || return 1
+  awk -v assistant="$name" -v target="$field" '
+    $0 ~ "^  " assistant ":$" { in_block=1; next }
+    in_block && $0 ~ "^  [^[:space:]]+:$" { exit }
+    in_block {
+      prefix = "    " target ": "
+      if (index($0, prefix) == 1) {
+        value = substr($0, length(prefix) + 1)
+        gsub(/^"|"$/, "", value)
+        print value
+        exit
+      }
+    }
+  ' "$WORK_ALLY_ASSISTANT_REGISTRY_FILE"
+}
+
+work_ally_require_registered_assistant() {
+  local name="$1"
+  work_ally_validate_assistant_name "$name"
+  if ! work_ally_registry_has_assistant "$name"; then
+    work_ally_die "Assistant not registered: $name. Run '$(work_ally_cmd_name) assistant list' or '$(work_ally_cmd_name) assistant add $name'."
+  fi
+}
+
+work_ally_assistant_description() {
+  local name="$1"
+  work_ally_registry_field "$name" description || true
+}
+
+work_ally_assistant_registered_home() {
+  local name="$1"
+  work_ally_registry_field "$name" assistant_home || true
+}
+
+work_ally_assistant_registered_codex_home() {
+  local name="$1"
+  work_ally_registry_field "$name" codex_home || true
+}
+
+work_ally_assistant_registered_workspace() {
+  local name="$1"
+  work_ally_project_registry_workspace_for_assistant "$name" || true
+}
+
+work_ally_registry_remove_assistant() {
+  local name="$1"
+  local tmp
+  [ -f "$WORK_ALLY_ASSISTANT_REGISTRY_FILE" ] || return 0
+  tmp=$(mktemp "${TMPDIR:-/tmp}/work-ally-assistant-registry.XXXXXX")
+
+  awk -v assistant="$name" '
+    BEGIN { skip = 0 }
+    $0 ~ "^  " assistant ":$" {
+      skip = 1
+      next
+    }
+    skip && /^    / { next }
+    skip { skip = 0 }
+    { print }
+  ' "$WORK_ALLY_ASSISTANT_REGISTRY_FILE" > "$tmp"
+
+  if ! grep -q '^assistants:$' "$tmp"; then
+    printf 'assistants:\n' | cat - "$tmp" > "$tmp.with-header"
+    mv "$tmp.with-header" "$tmp"
+  fi
+
+  mv "$tmp" "$WORK_ALLY_ASSISTANT_REGISTRY_FILE"
+}
+
+work_ally_assistant_is_busy() {
+  local name="$1"
+  local lock_file lock_pid
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  [ -f "$lock_file" ] || return 1
+  lock_pid=$(work_ally_assistant_lock_field "$lock_file" pid || true)
+  if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+    return 0
+  fi
+  return 1
+}
+
+work_ally_workspace_binding_count() {
+  local workspace_root="${1:-$WORK_ALLY_WORKSPACE_ROOT}"
+  local assistants
+  assistants=$(work_ally_project_registry_assistants_for_workspace "$workspace_root" || true)
+  printf '%s\n' "$assistants" | awk 'NF { count += 1 } END { print count + 0 }'
+}
+
+work_ally_assistant_workspace_root_or_die() {
+  local name="$1"
+  local workspace_root
+  workspace_root=$(work_ally_assistant_registered_workspace "$name" || true)
+  [ -n "$workspace_root" ] || work_ally_die "Assistant $name is not bound to a project yet. Re-run '$(work_ally_cmd_name) setup $name --workspace <path>'."
+  printf '%s\n' "$workspace_root"
+}
+
+work_ally_sync_workspace_root_from_assistant() {
+  local name="$1"
+  local workspace_root
+  workspace_root=$(work_ally_assistant_workspace_root_or_die "$name")
+  export WORK_ALLY_WORKSPACE_ROOT="$workspace_root"
+}
+
+work_ally_resolve_assistant_name_from_args() {
+  local default_name="${WORK_ALLY_ASSISTANT_NAME:-}"
+  local current_workspace binding_count
+  current_workspace="${WORK_ALLY_WORKSPACE_ROOT:-}"
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --assistant)
+        [ "$#" -ge 2 ] || work_ally_die "--assistant requires a value"
+        printf '%s\n' "$2"
+        return 0
+        ;;
+      --assistant=*)
+        printf '%s\n' "${1#--assistant=}"
+        return 0
+        ;;
+    esac
+    shift
+  done
+
+  if [ -z "$default_name" ] && [ -n "$current_workspace" ]; then
+    default_name=$(work_ally_resolve_registered_assistant_for_workspace "$current_workspace" || true)
+  fi
+
+  if [ -n "$default_name" ]; then
+    printf '%s\n' "$default_name"
+    return 0
+  fi
+
+  if [ -n "${WORK_ALLY_ASSISTANT_STATE_FILE:-}" ] && [ -f "$WORK_ALLY_ASSISTANT_STATE_FILE" ]; then
+    # shellcheck disable=SC1090
+    . "$WORK_ALLY_ASSISTANT_STATE_FILE"
+    if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+      printf '%s\n' "$WORK_ALLY_ASSISTANT_NAME"
+      return 0
+    fi
+  fi
+
+  if [ -n "$current_workspace" ]; then
+    binding_count=$(work_ally_workspace_binding_count "$current_workspace")
+    if [ "$binding_count" -gt 1 ]; then
+      work_ally_die "Multiple assistants are bound to $current_workspace. Use --assistant <name>."
+    fi
+  fi
+
+  work_ally_die "Assistant is required. Use --assistant <name> or run '$(work_ally_cmd_name) setup <name> --workspace <path>'."
+}
+
+work_ally_write_assistant_state() {
+  local name="$1"
+  local assistant_home="$2"
+  local codex_home="$3"
+  work_ally_hydrate_assistant_context "$name"
+  mkdir -p "$WORK_ALLY_RUNTIME_DIR"
+  {
+    printf 'WORK_ALLY_ASSISTANT_MODE=assistant\n'
+    printf 'WORK_ALLY_ASSISTANT_NAME=%s\n' "$name"
+    printf 'WORK_ALLY_ASSISTANT_HOME=%s\n' "$assistant_home"
+    printf 'WORK_ALLY_ASSISTANT_CODEX_HOME=%s\n' "$codex_home"
+    printf 'WORK_ALLY_WORKSPACE_ROOT=%s\n' "$WORK_ALLY_WORKSPACE_ROOT"
+    printf 'WORK_ALLY_INSTALL_ROOT=%s\n' "$WORK_ALLY_INSTALL_ROOT"
+    printf 'WORK_ALLY_IMPLEMENTATION_DIR=%s\n' "$WORK_ALLY_IMPLEMENTATION_DIR"
+    printf 'WORK_ALLY_INSTALL_CHANNEL=%s\n' "${WORK_ALLY_INSTALL_CHANNEL:-unknown}"
+    printf 'WORK_ALLY_STATE_DIR=%s\n' "$WORK_ALLY_STATE_DIR"
+  } > "$WORK_ALLY_ASSISTANT_STATE_FILE"
+}
+
+work_ally_load_assistant_state() {
+  [ -f "$WORK_ALLY_ASSISTANT_STATE_FILE" ] || return 1
+  set -a
+  # shellcheck disable=SC1090
+  . "$WORK_ALLY_ASSISTANT_STATE_FILE"
+  set +a
+}
+
+work_ally_require_assistant_profile_ready() {
+  local name="$1"
+  local assistant_home codex_home assistant_agents config_file
+
+  work_ally_require_registered_assistant "$name"
+  assistant_home=$(work_ally_assistant_registered_home "$name")
+  codex_home=$(work_ally_assistant_registered_codex_home "$name")
+  [ -n "$assistant_home" ] || work_ally_die "Assistant profile is invalid: missing assistant_home for $name"
+  [ -n "$codex_home" ] || work_ally_die "Assistant profile is invalid: missing codex_home for $name"
+  [ -d "$assistant_home" ] || work_ally_die "Assistant profile is incomplete: missing assistant_home at $assistant_home"
+  [ -d "$codex_home" ] || work_ally_die "Assistant profile is incomplete: missing codex_home at $codex_home"
+  assistant_agents="$codex_home/AGENTS.md"
+  config_file="$codex_home/config.toml"
+  [ -f "$assistant_agents" ] || work_ally_die "Assistant profile is incomplete: missing $assistant_agents"
+  [ -f "$config_file" ] || work_ally_die "Assistant profile is incomplete: missing $config_file"
+}
+
+work_ally_global_lock_dir() {
+  printf '%s/locks\n' "$WORK_ALLY_HOME"
+}
+
+work_ally_assistant_lock_file() {
+  local name="$1"
+  printf '%s/assistant-%s.lock\n' "$(work_ally_global_lock_dir)" "$name"
+}
+
+work_ally_emit_assistant_lock_content() {
+  local owner_pid="$1"
+  printf 'assistant=%s\n' "${WORK_ALLY_ASSISTANT_NAME:-}"
+  printf 'workspace_root=%s\n' "$WORK_ALLY_WORKSPACE_ROOT"
+  printf 'pid=%s\n' "$owner_pid"
+  printf 'updated_at=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+
+work_ally_assistant_lock_field() {
+  local file="$1"
+  local key="$2"
+  [ -f "$file" ] || return 1
+  sed -n "s/^${key}=//p" "$file" | head -n 1
+}
+
+work_ally_assert_assistant_available() {
+  local name="$1"
+  local lock_file lock_pid lock_workspace
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  mkdir -p "$(dirname "$lock_file")"
+  [ -f "$lock_file" ] || return 0
+
+  lock_pid=$(work_ally_assistant_lock_field "$lock_file" pid || true)
+  lock_workspace=$(work_ally_assistant_lock_field "$lock_file" workspace_root || true)
+
+  if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+    if [ -z "$lock_workspace" ] || [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+      return 0
+    fi
+    work_ally_die "Assistant $name is already active in project $lock_workspace (pid $lock_pid). Stop it first before using the same assistant elsewhere."
+  fi
+
+  rm -f "$lock_file"
+}
+
+work_ally_claim_assistant_lock() {
+  local name="$1"
+  local owner_pid="${2:-$$}"
+  local lock_file lock_pid lock_workspace
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  mkdir -p "$(dirname "$lock_file")"
+
+  while :; do
+    if ( set -C; work_ally_emit_assistant_lock_content "$owner_pid" > "$lock_file" ) 2>/dev/null; then
+      return 0
+    fi
+
+    lock_pid=$(work_ally_assistant_lock_field "$lock_file" pid || true)
+    lock_workspace=$(work_ally_assistant_lock_field "$lock_file" workspace_root || true)
+
+    if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+      if [ -z "$lock_workspace" ] || [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+        work_ally_write_assistant_lock "$name" "$owner_pid"
+        return 0
+      fi
+      work_ally_die "Assistant $name is already active in project $lock_workspace (pid $lock_pid). Stop it first before using the same assistant elsewhere."
+    fi
+
+    rm -f "$lock_file"
+  done
+}
+
+work_ally_write_assistant_lock() {
+  local name="$1"
+  local owner_pid="$2"
+  local lock_file
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  mkdir -p "$(dirname "$lock_file")"
+  work_ally_emit_assistant_lock_content "$owner_pid" > "$lock_file"
+}
+
+work_ally_assistant_lock_status() {
+  local name="$1"
+  local lock_file lock_pid lock_workspace
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  [ -f "$lock_file" ] || {
+    printf 'none\n'
+    return 0
+  }
+  lock_pid=$(work_ally_assistant_lock_field "$lock_file" pid || true)
+  lock_workspace=$(work_ally_assistant_lock_field "$lock_file" workspace_root || true)
+  if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+    if [ -n "$lock_workspace" ] && [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+      printf 'owned\n'
+    else
+      printf 'busy\n'
+    fi
+    return 0
+  fi
+  printf 'stale\n'
+}
+
+work_ally_release_assistant_lock() {
+  local name="$1"
+  local expected_pid="${2:-}"
+  local lock_file lock_workspace lock_pid
+  lock_file=$(work_ally_assistant_lock_file "$name")
+  [ -f "$lock_file" ] || return 0
+  lock_workspace=$(work_ally_assistant_lock_field "$lock_file" workspace_root || true)
+  lock_pid=$(work_ally_assistant_lock_field "$lock_file" pid || true)
+  if [ -n "$lock_workspace" ] && [ "$lock_workspace" != "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+    return 0
+  fi
+  if [ -n "$expected_pid" ] && [ -n "$lock_pid" ] && [ "$expected_pid" != "$lock_pid" ]; then
+    return 0
+  fi
+  rm -f "$lock_file"
+}
+
+work_ally_env_template_file() {
+  printf '%s/templates/env.example\n' "$WORK_ALLY_IMPLEMENTATION_DIR"
+}
+
+work_ally_env_set() {
+  local key="$1"
+  local value="$2"
+  local tmp
+
+  mkdir -p "$(dirname "$WORK_ALLY_ENV_FILE")"
+  tmp=$(mktemp "${TMPDIR:-/tmp}/work-ally-env-set.XXXXXX")
+
+  if [ -f "$WORK_ALLY_ENV_FILE" ]; then
+    awk -v key="$key" -v value="$value" '
+      BEGIN { updated = 0 }
+      index($0, key "=") == 1 {
+        if (!updated) {
+          printf "%s=%s\n", key, value
+          updated = 1
+        }
+        next
+      }
+      { print }
+      END {
+        if (!updated) {
+          printf "%s=%s\n", key, value
+        }
+      }
+    ' "$WORK_ALLY_ENV_FILE" > "$tmp"
+  else
+    printf '%s=%s\n' "$key" "$value" > "$tmp"
+  fi
+
+  mv "$tmp" "$WORK_ALLY_ENV_FILE"
+}
+
+work_ally_assistant_autosave_interval() {
+  local value="${WORK_ALLY_ASSISTANT_AUTOSAVE_INTERVAL_SECONDS:-1800}"
+  case "$value" in
+    ''|*[!0-9]*) printf '1800\n' ;;
+    *)
+      if [ "$value" -lt 1 ]; then
+        printf '1800\n'
+      else
+        printf '%s\n' "$value"
+      fi
+      ;;
+  esac
+}
+
+work_ally_ensure_env_defaults() {
+  local template tmp changed line key current_emoji
+  template=$(work_ally_env_template_file)
+  export WORK_ALLY_ENV_UPDATED=0
+
+  [ -f "$template" ] || work_ally_die "Missing env template: $template"
+
+  if [ ! -f "$WORK_ALLY_ENV_FILE" ]; then
+    cp "$template" "$WORK_ALLY_ENV_FILE"
+    export WORK_ALLY_ENV_UPDATED=1
+    work_ally_ok "Created assistant config: $WORK_ALLY_ENV_FILE"
+    return 0
+  fi
+
+  tmp=$(mktemp "${TMPDIR:-/tmp}/work-ally-env.XXXXXX")
+  cp "$WORK_ALLY_ENV_FILE" "$tmp"
+  changed=0
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in
+      ''|'#'*)
+        continue
+        ;;
+    esac
+    key=${line%%=*}
+    if ! grep -Eq "^${key}=" "$tmp"; then
+      printf '\n%s\n' "$line" >> "$tmp"
+      changed=1
+    fi
+  done < "$template"
+
+  current_emoji=$(grep -E '^FEISHU_REACT_EMOJI=' "$tmp" | tail -n 1 | cut -d= -f2- || true)
+  if [ "$current_emoji" = "OnIt" ]; then
+    awk '{ if ($0 == "FEISHU_REACT_EMOJI=OnIt") print "FEISHU_REACT_EMOJI=Typing"; else print $0 }' "$tmp" > "$tmp.rewritten"
+    mv "$tmp.rewritten" "$tmp"
+    changed=1
+  fi
+
+  if [ "$changed" -eq 1 ]; then
+    mv "$tmp" "$WORK_ALLY_ENV_FILE"
+    export WORK_ALLY_ENV_UPDATED=1
+    work_ally_note "Updated assistant config defaults: $WORK_ALLY_ENV_FILE"
+  else
+    rm -f "$tmp"
+  fi
+}
+
+work_ally_load_env() {
+  local env_file="${WORK_ALLY_ENV_FILE:-}"
+  [ -n "$env_file" ] || return 0
+  if [ -f "$env_file" ]; then
+    set -a
+    # shellcheck disable=SC1090
+    . "$env_file"
+    set +a
+  fi
+}
+
+work_ally_codex_required_env_keys() {
+  local codex_home config_file keys
+  codex_home="${WORK_ALLY_ASSISTANT_CODEX_HOME:-${CODEX_HOME:-}}"
+  [ -n "$codex_home" ] || return 0
+  config_file="$codex_home/config.toml"
+  [ -f "$config_file" ] || return 0
+  keys=$(sed -nE 's/^[[:space:]]*env_key[[:space:]]*=[[:space:]]*"([^"]+)"[[:space:]]*$/\1/p' "$config_file" | awk '!seen[$0]++')
+  [ -n "$keys" ] || return 0
+  printf '%s\n' "$keys"
+}
+
+work_ally_assert_codex_env_keys_available() {
+  local key missing=0
+  while IFS= read -r key; do
+    [ -n "$key" ] || continue
+    if [ -z "${!key:-}" ]; then
+      work_ally_warn "Missing required environment variable for Codex provider: $key"
+      missing=1
+    fi
+  done <<EOF
+$(work_ally_codex_required_env_keys)
+EOF
+
+  if [ "$missing" -eq 1 ]; then
+    work_ally_die "Codex provider environment variables are missing. Export them in the shell before running $(work_ally_cmd_name) start."
+  fi
+}
+
+work_ally_pid_file() {
+  printf '%s/%s.pid\n' "$WORK_ALLY_RUNTIME_DIR" "$1"
+}
+
+work_ally_health_file() {
+  printf '%s/%s.health.json\n' "$WORK_ALLY_RUNTIME_DIR" "$1"
+}
+
+work_ally_json_field() {
+  local file="$1"
+  local key="$2"
+  [ -f "$file" ] || return 0
+  sed -nE "s/.*\"${key}\"[[:space:]]*:[[:space:]]*\"([^\"]*)\".*/\\1/p" "$file" | head -n 1
+}
+
+work_ally_json_number_field() {
+  local file="$1"
+  local key="$2"
+  [ -f "$file" ] || return 0
+  sed -nE "s/.*\"${key}\"[[:space:]]*:[[:space:]]*([0-9]+).*/\\1/p" "$file" | head -n 1
+}
+
+work_ally_is_pid_alive() {
+  local pid="$1"
+  [ -n "$pid" ] && kill -0 "$pid" >/dev/null 2>&1
+}
+
+work_ally_read_pid() {
+  local file="$1"
+  local pid
+  [ -f "$file" ] || return 1
+  pid=$(tr -d '[:space:]' < "$file")
+  [ -n "$pid" ] || return 1
+  printf '%s\n' "$pid"
+}
+
+work_ally_terminate_pid() {
+  local pid="$1"
+  local attempt=0
+
+  [ -n "$pid" ] || return 0
+  if ! work_ally_is_pid_alive "$pid"; then
+    return 0
+  fi
+
+  kill "$pid" >/dev/null 2>&1 || true
+  while [ "$attempt" -lt 5 ]; do
+    if ! work_ally_is_pid_alive "$pid"; then
+      return 0
+    fi
+    attempt=$((attempt + 1))
+    sleep 1
+  done
+
+  if work_ally_is_pid_alive "$pid"; then
+    kill -9 "$pid" >/dev/null 2>&1 || true
+  fi
+}
+
+work_ally_is_external_owner() {
+  local health_file
+  health_file=$(work_ally_health_file "$1")
+  [ -f "$health_file" ] || return 1
+  grep -Eq '"owner"[[:space:]]*:[[:space:]]*"external"' "$health_file"
+}
+
+work_ally_health_pid() {
+  local health_file
+  health_file=$(work_ally_health_file "$1")
+  [ -f "$health_file" ] || return 1
+  sed -nE 's/.*"pid"[[:space:]]*:[[:space:]]*([0-9]+).*/\1/p' "$health_file" | head -n 1
+}
+
+work_ally_bridge_entrypoint() {
+  work_ally_abs_path "$WORK_ALLY_IMPLEMENTATION_DIR/bridge/src/server.ts"
+}
+
+work_ally_list_bridge_pids() {
+  local pid_file health_pid
+  pid_file=$(work_ally_pid_file bridge)
+
+  {
+    work_ally_read_pid "$pid_file" || true
+    health_pid=$(work_ally_health_pid bridge || true)
+    if [ -n "$health_pid" ]; then
+      printf '%s\n' "$health_pid"
+    fi
+  } | awk 'NF && !seen[$0]++ { print $0 }' | while IFS= read -r pid; do
+      [ -n "$pid" ] || continue
+      if work_ally_is_pid_alive "$pid"; then
+        printf '%s\n' "$pid"
+      fi
+    done
+}
+work_ally_primary_bridge_pid() {
+  local pid_file pid live
+  pid_file=$(work_ally_pid_file bridge)
+  pid=$(work_ally_read_pid "$pid_file" || true)
+  if [ -n "$pid" ] && work_ally_is_pid_alive "$pid"; then
+    live=$(work_ally_list_bridge_pids || true)
+    if [ -z "$live" ] || printf '%s\n' "$live" | grep -qx "$pid"; then
+      printf '%s\n' "$pid"
+      return 0
+    fi
+  fi
+
+  work_ally_list_bridge_pids | awk 'NF { print; exit }'
+}
+
+work_ally_bridge_pid_count() {
+  work_ally_list_bridge_pids | awk 'NF { count += 1 } END { print count + 0 }'
+}
+
+work_ally_stop_bridge_processes() {
+  local pid_file
+  pid_file=$(work_ally_pid_file bridge)
+
+  {
+    work_ally_read_pid "$pid_file" || true
+    work_ally_list_bridge_pids || true
+  } | awk 'NF && !seen[$0]++ { print $0 }' | while IFS= read -r pid; do
+      [ -n "$pid" ] || continue
+      if work_ally_is_pid_alive "$pid"; then
+        work_ally_terminate_pid "$pid"
+      fi
+    done
+
+  rm -f "$pid_file"
+  work_ally_write_health bridge stopped '{}'
+  work_ally_release_channel_lock
+  if [ -n "${WORK_ALLY_ASSISTANT_NAME:-}" ]; then
+    work_ally_release_assistant_lock "$WORK_ALLY_ASSISTANT_NAME"
+  fi
+}
+
+work_ally_process_status() {
+  local name="$1"
+
+  if [ "$name" = "bridge" ]; then
+    local bridge_pids bridge_count bridge_joined
+    bridge_pids=$(work_ally_list_bridge_pids || true)
+    bridge_count=$(printf '%s\n' "$bridge_pids" | awk 'NF { count += 1 } END { print count + 0 }')
+    if [ "$bridge_count" -gt 1 ]; then
+      bridge_joined=$(printf '%s\n' "$bridge_pids" | awk 'NF' | paste -sd ',' -)
+      printf 'running (multiple: %s)\n' "$bridge_joined"
+      return 0
+    fi
+    if [ "$bridge_count" -eq 1 ]; then
+      printf 'running (%s)\n' "$(printf '%s\n' "$bridge_pids" | awk 'NF { print; exit }')"
+      return 0
+    fi
+  fi
+
+  local pid_file pid
+  pid_file=$(work_ally_pid_file "$name")
+  if [ ! -f "$pid_file" ]; then
+    if work_ally_is_external_owner "$name"; then
+      printf 'running (external)\n'
+      return 0
+    fi
+    printf 'stopped\n'
+    return 0
+  fi
+
+  pid=$(work_ally_read_pid "$pid_file" || true)
+  if work_ally_is_pid_alive "$pid"; then
+    printf 'running (%s)\n' "$pid"
+    return 0
+  fi
+
+  if work_ally_is_external_owner "$name"; then
+    printf 'running (external)\n'
+    return 0
+  fi
+
+  printf 'stale (%s)\n' "${pid:-unknown}"
+}
+
+work_ally_log_retention_days() {
+  local value="${WORK_ALLY_LOG_RETENTION_DAYS:-3}"
+  case "$value" in
+    ''|*[!0-9]*) printf '3\n' ;;
+    *)
+      if [ "$value" -lt 1 ]; then
+        printf '3\n'
+      else
+        printf '%s\n' "$value"
+      fi
+      ;;
+  esac
+}
+
+
+work_ally_global_runtime_dir() {
+  printf '%s\n' "${WORK_ALLY_GLOBAL_RUNTIME_DIR:-${TMPDIR:-/tmp}/work-ally-runtime}"
+}
+
+work_ally_channel_lock_key() {
+  local channel_impl="${WORK_ALLY_CHANNEL_IMPL:-feishu}"
+  case "$channel_impl" in
+    feishu)
+      [ -n "${FEISHU_APP_ID:-}" ] || return 1
+      printf 'feishu-%s\n' "$FEISHU_APP_ID" | tr -c 'A-Za-z0-9._-' '_'
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+}
+
+work_ally_channel_lock_file() {
+  local key
+  key=$(work_ally_channel_lock_key || true)
+  [ -n "$key" ] || return 1
+  printf '%s/channel-locks/%s.lock\n' "$(work_ally_global_runtime_dir)" "$key"
+}
+
+work_ally_channel_lock_field() {
+  local file="$1"
+  local key="$2"
+  [ -f "$file" ] || return 1
+  sed -n "s/^${key}=//p" "$file" | head -n 1
+}
+
+work_ally_emit_channel_lock_content() {
+  local owner_pid="$1"
+  printf 'channel=%s\n' "${WORK_ALLY_CHANNEL_IMPL:-}"
+  printf 'app_id=%s\n' "${FEISHU_APP_ID:-}"
+  printf 'workspace_root=%s\n' "$WORK_ALLY_WORKSPACE_ROOT"
+  printf 'pid=%s\n' "$owner_pid"
+  printf 'updated_at=%s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+}
+
+work_ally_assert_channel_available() {
+  local lock_file lock_pid lock_workspace
+  lock_file=$(work_ally_channel_lock_file || true)
+  [ -n "$lock_file" ] || return 0
+  mkdir -p "$(dirname "$lock_file")"
+  [ -f "$lock_file" ] || return 0
+
+  lock_pid=$(work_ally_channel_lock_field "$lock_file" pid || true)
+  lock_workspace=$(work_ally_channel_lock_field "$lock_file" workspace_root || true)
+
+  if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+    if [ -z "$lock_workspace" ] || [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+      return 0
+    fi
+    work_ally_die "Feishu app ${FEISHU_APP_ID:-unknown} is already active in workspace $lock_workspace (bridge pid $lock_pid). Stop it first or use a dedicated bot/app."
+  fi
+
+  rm -f "$lock_file"
+}
+
+work_ally_claim_channel_lock() {
+  local owner_pid lock_file lock_pid lock_workspace
+  owner_pid="${1:-$$}"
+  lock_file=$(work_ally_channel_lock_file || true)
+  [ -n "$lock_file" ] || return 0
+  mkdir -p "$(dirname "$lock_file")"
+
+  while :; do
+    if ( set -C; work_ally_emit_channel_lock_content "$owner_pid" > "$lock_file" ) 2>/dev/null; then
+      return 0
+    fi
+
+    lock_pid=$(work_ally_channel_lock_field "$lock_file" pid || true)
+    lock_workspace=$(work_ally_channel_lock_field "$lock_file" workspace_root || true)
+
+    if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+      if [ -z "$lock_workspace" ] || [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+        work_ally_write_channel_lock "$owner_pid"
+        return 0
+      fi
+      work_ally_die "Feishu app ${FEISHU_APP_ID:-unknown} is already active in workspace $lock_workspace (bridge pid $lock_pid). Stop it first or use a dedicated bot/app."
+    fi
+
+    rm -f "$lock_file"
+  done
+}
+
+work_ally_write_channel_lock() {
+  local bridge_pid="$1"
+  local lock_file
+  lock_file=$(work_ally_channel_lock_file || true)
+  [ -n "$lock_file" ] || return 0
+  mkdir -p "$(dirname "$lock_file")"
+  work_ally_emit_channel_lock_content "$bridge_pid" > "$lock_file"
+}
+
+work_ally_channel_lock_status() {
+  local lock_file lock_pid lock_workspace
+  lock_file=$(work_ally_channel_lock_file || true)
+  [ -n "$lock_file" ] || return 0
+  if [ ! -f "$lock_file" ]; then
+    printf 'none\n'
+    return 0
+  fi
+
+  lock_pid=$(work_ally_channel_lock_field "$lock_file" pid || true)
+  lock_workspace=$(work_ally_channel_lock_field "$lock_file" workspace_root || true)
+
+  if [ -n "$lock_pid" ] && work_ally_is_pid_alive "$lock_pid"; then
+    if [ -n "$lock_workspace" ] && [ "$lock_workspace" = "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+      printf 'owned\n'
+    else
+      printf 'busy\n'
+    fi
+    return 0
+  fi
+
+  printf 'stale\n'
+}
+
+work_ally_release_channel_lock() {
+  local lock_file lock_workspace lock_pid expected_pid
+  expected_pid="${1:-}"
+  lock_file=$(work_ally_channel_lock_file || true)
+  [ -n "$lock_file" ] || return 0
+  [ -f "$lock_file" ] || return 0
+
+  lock_workspace=$(work_ally_channel_lock_field "$lock_file" workspace_root || true)
+  lock_pid=$(work_ally_channel_lock_field "$lock_file" pid || true)
+
+  if [ -n "$lock_workspace" ] && [ "$lock_workspace" != "$WORK_ALLY_WORKSPACE_ROOT" ]; then
+    return 0
+  fi
+  if [ -n "$expected_pid" ] && [ -n "$lock_pid" ] && [ "$expected_pid" != "$lock_pid" ]; then
+    return 0
+  fi
+
+  rm -f "$lock_file"
+}
+
+work_ally_log_file_for() {
+  local name="$1"
+  local stamp
+  if [ -n "${WORK_ALLY_TIMEZONE:-}" ]; then
+    stamp=$(TZ="$WORK_ALLY_TIMEZONE" date +%F 2>/dev/null || date +%F)
+  else
+    stamp=$(date +%F)
+  fi
+  printf '%s/%s-%s.log\n' "$WORK_ALLY_LOG_DIR" "$name" "$stamp"
+}
+
+work_ally_prune_logs() {
+  local retention name file now epoch threshold stamp
+  retention=$(work_ally_log_retention_days)
+  now=$(date +%s)
+  threshold=$((retention * 24 * 60 * 60))
+  for file in "$WORK_ALLY_LOG_DIR"/*.log; do
+    [ -e "$file" ] || continue
+    name=$(basename "$file")
+    case "$name" in
+      *-????-??-??.log)
+        stamp=${name##*-}
+        stamp=${stamp%.log}
+        if epoch=$(date -j -f %F "$stamp" +%s 2>/dev/null); then
+          if [ $((now - epoch)) -gt "$threshold" ]; then
+            rm -f "$file"
+          fi
+        fi
+        ;;
+    esac
+  done
+}
+
+work_ally_tail_log() {
+  local name="$1"
+  local file
+  file=$(work_ally_log_file_for "$name")
+  mkdir -p "$WORK_ALLY_LOG_DIR"
+  [ -f "$file" ] || touch "$file"
+  work_ally_prune_logs
+  tail -f "$file"
+}
+
+work_ally_json_escape() {
+  local value="${1-}"
+  value=${value//\\/\\\\}
+  value=${value//\"/\\\"}
+  value=${value//$'\n'/\\n}
+  value=${value//$'\r'/\\r}
+  value=${value//$'\t'/\\t}
+  printf '%s' "$value"
+}
+
+work_ally_health_delivery_fields_json() {
+  local file="$1"
+  [ -f "$file" ] || return 0
+
+  local status channel kind code message guidance updated
+  status=$(work_ally_json_field "$file" delivery_status)
+  [ -n "$status" ] || return 0
+  channel=$(work_ally_json_field "$file" delivery_channel)
+  kind=$(work_ally_json_field "$file" delivery_error_kind)
+  code=$(work_ally_json_field "$file" delivery_error_code)
+  message=$(work_ally_json_field "$file" delivery_message)
+  guidance=$(work_ally_json_field "$file" delivery_guidance)
+  updated=$(work_ally_json_field "$file" delivery_updated_at)
+
+  printf '  "delivery_status": "%s",\n' "$(work_ally_json_escape "$status")"
+  [ -n "$channel" ] && printf '  "delivery_channel": "%s",\n' "$(work_ally_json_escape "$channel")"
+  [ -n "$kind" ] && printf '  "delivery_error_kind": "%s",\n' "$(work_ally_json_escape "$kind")"
+  [ -n "$code" ] && printf '  "delivery_error_code": "%s",\n' "$(work_ally_json_escape "$code")"
+  [ -n "$message" ] && printf '  "delivery_message": "%s",\n' "$(work_ally_json_escape "$message")"
+  [ -n "$guidance" ] && printf '  "delivery_guidance": "%s",\n' "$(work_ally_json_escape "$guidance")"
+  [ -n "$updated" ] && printf '  "delivery_updated_at": "%s",\n' "$(work_ally_json_escape "$updated")"
+}
+
+work_ally_write_health() {
+  local name="$1"
+  local status="$2"
+  local extra_json health_file delivery_json
+  if [ "$#" -ge 3 ] && [ -n "$3" ]; then
+    extra_json="$3"
+  else
+    extra_json='{}'
+  fi
+
+  health_file="$(work_ally_health_file "$name")"
+  delivery_json=""
+  if [ "$name" = "bridge" ]; then
+    delivery_json=$(work_ally_health_delivery_fields_json "$health_file")
+  fi
+
+  {
+    printf '{\n'
+    printf '  "status": "%s",\n' "$status"
+    printf '  "updated_at": "%s",\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    if [ -n "$delivery_json" ]; then
+      printf '%s' "$delivery_json"
+    fi
+    printf '  "extra": %s\n' "$extra_json"
+    printf '}\n'
+  } > "$health_file"
+}
+
+work_ally_install_bridge_dependencies() {
+  local package_dir="$WORK_ALLY_IMPLEMENTATION_DIR"
+  local cache_dir="${WORK_ALLY_NPM_CACHE_DIR:-$package_dir/.npm-cache}"
+  if [ -d "$package_dir/node_modules" ]; then
+    return 0
+  fi
+  work_ally_require_cmd npm
+  work_ally_note "Installing bridge dependencies"
+  (
+    cd "$package_dir"
+    export npm_config_cache="$cache_dir"
+    export NPM_CONFIG_CACHE="$cache_dir"
+    if [ -f package-lock.json ]; then
+      npm ci --cache "$cache_dir"
+    else
+      npm install --cache "$cache_dir"
+    fi
+  )
+  work_ally_ok "Bridge dependencies installed"
+}