@devrouter/cli 0.0.29 → 0.0.31

package/README.md

@@ -108,11 +108,18 @@ vars. Use it when you are not (yet) on a devcontainer. Fully supported.
 - `devrouter workspace up <branch> [--path <dir>] [--no-devpod] [--open] [--repo <path>]`
 - `devrouter workspace ensure [path] [--open]`
 - `devrouter workspace ls [--repo <path>] [--json]`
-- `devrouter workspace down <workspace|branch> [--keep-worktree] [--keep-devpod] [--repo <path>]`
+- `devrouter workspace stop <workspace|branch> [--repo <path>]`
+- `devrouter workspace down <workspace|branch> [--keep-worktree] [--repo <path>]`
+- `devrouter workspace gc [--repo <path>] [--json] [--yes]`
 
 The current `devrouter repo devcontainer write` scaffold is intentionally narrow:
 Node + pnpm + Postgres. Other package managers stop with a JSON diagnostic
 instead of writing files that would need manual repair.
+The generated image extracts `devrouter-process` from the exact Devrouter
+package tarball without installing the CLI dependency tree. Its `post-start.sh`
+uses that helper for locked, owned, idempotent background startup. Application
+commands and environment setup remain repository-owned; route readiness remains
+part of `devrouter workspace ensure`.
 Use `devrouter repo devcontainer verify --json` for read-only PR evidence; add
 `--live --yes` only after the devcontainer is running and route probes should
 mutate local route state.
@@ -121,12 +128,13 @@ mutate local route state.
 
 A **workspace token** lets several git worktrees of the same repo run side-by-side without host or route collisions. The token is a single identity spanning three layers: the devpod workspace id, the routes devrouter registers, and the `${WORKSPACE}` placeholder in `.devrouter.yml` proxy upstreams and devcontainer compose network aliases.
 
-Each linked worktree stores one stable identity in its Git metadata. Once stored,
-that value is authoritative: an explicit flag or `DEVROUTER_WORKSPACE` may repeat
-it but cannot silently rename the environment. On first use, devrouter reuses the
-exact DevPod already bound to the worktree path or derives a sanitized identity
-from the linked branch/path. Ambiguous identities and DevPods owned by another
-worktree fail closed. The primary checkout keeps its plain, non-namespaced routes.
+Each managed linked worktree keeps its local token in Git metadata and a durable
+owner record under the repository's Git common directory. The record survives
+out-of-band linked-worktree removal and ties the exact worktree path to its DevPod
+ID. On first use, devrouter reuses an exact-path DevPod or derives a sanitized
+identity from the linked branch/path. Ambiguous identities and DevPods owned by
+another worktree fail closed. The primary checkout keeps its plain,
+non-namespaced routes.
 
 **When a workspace token is active:**
 
@@ -146,15 +154,41 @@ devrouter workspace up feat/my-feature
 # Reconcile an existing linked worktree (canonical agent startup command)
 devrouter workspace ensure .
 
-# List git worktrees with workspace tokens and route counts
+# List ownership, Git, DevPod, and route state
 devrouter workspace ls
 
-# Tear down a workspace (stop devpod, remove worktree, free routes)
+# Pause runtime while preserving the checkout, owner record, and data
+devrouter workspace stop feat/my-feature
+
+# Delete runtime and routes, then remove the clean worktree and owner record
 devrouter workspace down feat/my-feature
+
+# Review missing owners; add --yes only after reviewing the dry run
+devrouter workspace gc
+devrouter workspace gc --yes
 ```
 
 New worktrees default to the repository's ignored `trees/<workspace>` directory; use `--path` only when a repository intentionally follows another layout.
 
+| Command | DevPod | Routes | Worktree and owner record |
+| --- | --- | --- | --- |
+| `workspace stop` | stop | remove | keep |
+| `workspace down` | delete | remove | remove only when clean and unlocked |
+| `workspace down --keep-worktree` | delete | remove | keep |
+| `workspace gc` | report only | report only | never removes Git worktrees |
+| `workspace gc --yes` | delete eligible missing owners | remove exact owned routes | remove only the owner record |
+
+`workspace ls` reports owner status as `present`, `missing`, `locked`, or
+`conflict`. Full `workspace down` checks ownership, the Git registration, lock,
+and cleanliness before changing runtime or routes; dirty and locked worktrees fail
+with zero teardown side effects.
+
+Workspace lifecycle commands require a Git repository. Normal config, app,
+status, and diagnostic commands remain usable from a `.devrouter.yml` directory
+without Git. Git has no worktree-removal hook, so devrouter does not install one:
+after manual removal, use `workspace ls`, `doctor`, or the dry-run
+`workspace gc` report before applying cleanup with `--yes`.
+
 **devcontainer integration:** the devcontainer compose service exposes a devnet network alias `${WORKSPACE}-app` (defaulting to the project name in `devcontainer.env`); the proxy app uses `upstream: ${WORKSPACE}-app:<port>`. `.devcontainer/docker-compose.devrouter.yml` passes `WORKSPACE` and `DEVROUTER_WORKSPACE` into the app and bind-mounts `${DEVROUTER_GIT_COMMON_DIR}` to the same absolute container path, so linked-worktree `.git` pointers remain valid. Workspace `feat-a` → alias `feat-a-app`, host `app.feat-a.localhost`.
 
 `workspace ensure` is intentionally proof-driven: it verifies exact worktree
@@ -171,7 +205,10 @@ agent-native devcontainer path end to end — `./run.sh` brings up a DevPod
 workspace, registers app/Postgres proxy routes, runs static/live verification,
 and prints the proof. `./run.sh down` tears it down.
 
-**Orphan detection:** `devrouter doctor` check `routes.orphaned-workspace-routes` reports proxy routes whose worktree directory was removed without `devrouter workspace down`. It does not mutate route state.
+**Missing-owner detection:** `devrouter doctor` reports ledger-owned workspaces
+whose checkout disappeared or conflicts with live Git/DevPod evidence. It does
+not mutate workspace state and prints the exact dry-run remediation command:
+`devrouter workspace gc --repo <repo>`.
 
 ## Upgrade metadata and prompts
 
@@ -238,7 +275,7 @@ devrouter doctor --repo /absolute/path/to/repo --json
 For host apps that depend on postgres, `devrouter doctor` also checks host command wrapper precedence and warns with `repo.host-command-env-precedence` when `DATABASE_URI`/`DATABASE_URL` is assigned before a `run --` wrapper boundary.
 When TLS is enabled, `devrouter doctor` also checks TLS host coverage and warns with `repo.tls-host-coverage` if configured `.localhost` hosts are not covered by the current cert SANs.
 When `.devcontainer/` exists, `devrouter doctor` checks devnet aliases, published host ports, and proxy upstream alias matches.
-`devrouter doctor` reports stale host routes and orphaned workspace proxy routes without mutating route state.
+`devrouter doctor` reports stale host routes and ownership cleanup candidates without mutating route state; workspace findings point to dry-run `devrouter workspace gc --repo <repo>`.
 
 ## `.devrouter.yml` example
 

package/bin/devrouter-process

@@ -0,0 +1,274 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage:
+  devrouter-process ensure --name <name> --match <regex> [options] -- <command> [args...]
+
+Options:
+  --fingerprint <value>  Runtime identity. Defaults to command plus workspace identity.
+  --log <path>           Log file. Defaults to /tmp/devrouter-process-<name>.log.
+EOF
+}
+
+die() {
+  echo "[devrouter-process] $*" >&2
+  exit 1
+}
+
+require_value() {
+  [ "$#" -ge 2 ] || die "$1 requires a value."
+}
+
+[ "${1:-}" = "ensure" ] || {
+  usage >&2
+  exit 1
+}
+shift
+
+name=""
+process_match=""
+fingerprint=""
+log_file=""
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --name)
+      require_value "$@"
+      name="$2"
+      shift 2
+      ;;
+    --match)
+      require_value "$@"
+      process_match="$2"
+      shift 2
+      ;;
+    --fingerprint)
+      require_value "$@"
+      fingerprint="$2"
+      shift 2
+      ;;
+    --log)
+      require_value "$@"
+      log_file="$2"
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    --)
+      shift
+      break
+      ;;
+    *)
+      die "Unknown option: $1"
+      ;;
+  esac
+done
+
+[[ "$name" =~ ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ ]] || die "--name must be a safe identifier."
+[ -n "$process_match" ] || die "--match is required."
+[ "$#" -gt 0 ] || die "A command is required after --."
+[ -r "/proc/$$/environ" ] || die "Linux /proc process metadata is required."
+
+for tool in awk cksum flock grep pgrep ps setsid tr; do
+  command -v "$tool" >/dev/null 2>&1 || die "Required command is unavailable: $tool"
+done
+
+match_status=0
+pgrep -f -- "$process_match" >/dev/null 2>&1 || match_status=$?
+[ "$match_status" -le 1 ] || die "--match is not a valid process regular expression."
+
+if [ -z "$fingerprint" ]; then
+  fingerprint="$({
+    printf '%s\0' "$name" "${WORKSPACE:-}" "${DEVROUTER_WORKSPACE:-}"
+    printf '%s\0' "$@"
+  } | cksum | awk '{print $1 "-" $2}')"
+fi
+[[ "$fingerprint" =~ ^[a-zA-Z0-9][a-zA-Z0-9._:-]*$ ]] || die "--fingerprint must be a safe identifier."
+
+state_dir="${DEVROUTER_PROCESS_STATE_DIR:-/tmp}"
+state_file="$state_dir/devrouter-process-$name.state"
+lock_file="$state_file.lock"
+log_file="${log_file:-/tmp/devrouter-process-$name.log}"
+lock_timeout="${DEVROUTER_PROCESS_LOCK_TIMEOUT_SECONDS:-30}"
+term_timeout="${DEVROUTER_PROCESS_TERM_TIMEOUT_SECONDS:-15}"
+kill_timeout="${DEVROUTER_PROCESS_KILL_TIMEOUT_SECONDS:-5}"
+
+process_alive() {
+  local pid="$1"
+  local state
+
+  kill -0 "$pid" 2>/dev/null || return 1
+  state="$(ps -o stat= -p "$pid" 2>/dev/null | tr -d ' ')"
+  [[ "$state" != Z* ]]
+}
+
+process_owned() {
+  local pid="$1"
+  local pgid="$2"
+  local expected_fingerprint="$3"
+  local actual_pgid
+
+  [ -r "/proc/$pid/environ" ] || return 1
+  actual_pgid="$(ps -o pgid= -p "$pid" 2>/dev/null | tr -d ' ')"
+  [ "$actual_pgid" = "$pgid" ] || return 1
+  [ "$pgid" = "$pid" ] || return 1
+  tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
+    grep -Fqx "DEVROUTER_PROCESS_NAME=$name" || return 1
+  tr '\0' '\n' <"/proc/$pid/environ" 2>/dev/null |
+    grep -Fqx "DEVROUTER_PROCESS_FINGERPRINT=$expected_fingerprint"
+}
+
+process_group_alive() {
+  local pgid="$1"
+
+  ps -eo pgid=,stat= | awk -v expected="$pgid" '
+    $1 == expected && $2 !~ /^Z/ { found = 1 }
+    END { exit(found ? 0 : 1) }
+  '
+}
+
+is_self_or_ancestor() {
+  local candidate="$1"
+  local current="$$"
+
+  while [[ "$current" =~ ^[1-9][0-9]*$ ]]; do
+    [ "$candidate" = "$current" ] && return 0
+    [ "$current" -le 1 ] && break
+    current="$(ps -o ppid= -p "$current" 2>/dev/null | tr -d ' ')"
+  done
+  return 1
+}
+
+is_helper_process() {
+  local candidate="$1"
+
+  [ -r "/proc/$candidate/cmdline" ] || return 1
+  tr '\0' '\n' <"/proc/$candidate/cmdline" 2>/dev/null | grep -Fqx "$0"
+}
+
+marked_process_exists() {
+  local environ
+  local pid
+
+  for environ in /proc/[1-9]*/environ; do
+    [ -r "$environ" ] || continue
+    pid="${environ#/proc/}"
+    pid="${pid%/environ}"
+    process_alive "$pid" || continue
+    is_self_or_ancestor "$pid" && continue
+    if tr '\0' '\n' <"$environ" 2>/dev/null | grep -Fqx "DEVROUTER_PROCESS_NAME=$name"; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+matching_process_exists() {
+  local pid
+
+  while IFS= read -r pid; do
+    [ -n "$pid" ] || continue
+    [ -d "/proc/$pid" ] || continue
+    process_alive "$pid" || continue
+    is_self_or_ancestor "$pid" && continue
+    is_helper_process "$pid" && continue
+    return 0
+  done < <(pgrep -f -- "$process_match" 2>/dev/null || true)
+  return 1
+}
+
+unknown_process_exists() {
+  marked_process_exists || matching_process_exists
+}
+
+stop_process_group() {
+  local pid="$1"
+  local pgid="$2"
+  local attempt
+
+  kill -TERM -- "-$pgid" 2>/dev/null || true
+  for ((attempt = 1; attempt <= term_timeout; attempt += 1)); do
+    if ! process_group_alive "$pgid"; then
+      wait "$pid" 2>/dev/null || true
+      return 0
+    fi
+    sleep 1
+  done
+
+  kill -KILL -- "-$pgid" 2>/dev/null || true
+  for ((attempt = 1; attempt <= kill_timeout; attempt += 1)); do
+    if ! process_group_alive "$pgid"; then
+      wait "$pid" 2>/dev/null || true
+      return 0
+    fi
+    sleep 1
+  done
+
+  echo "[devrouter-process] Could not stop owned process group $pgid." >&2
+  return 1
+}
+
+mkdir -p "$state_dir" "$(dirname "$log_file")"
+exec 9>"$lock_file"
+flock -w "$lock_timeout" 9 || die "Timed out waiting for the '$name' process lock."
+
+pid=""
+pgid=""
+stored_fingerprint=""
+extra=""
+
+if [ -f "$state_file" ]; then
+  read -r pid pgid stored_fingerprint extra <"$state_file" || true
+  if [ -z "$stored_fingerprint" ] ||
+    ! [[ "$pid" =~ ^[1-9][0-9]*$ ]] ||
+    ! [[ "$pgid" =~ ^[1-9][0-9]*$ ]] ||
+    [ -n "$extra" ]; then
+    if unknown_process_exists; then
+      die "Invalid state while an unowned '$name' process is running; refusing to start or kill it."
+    fi
+    rm -f "$state_file"
+  elif process_alive "$pid"; then
+    process_owned "$pid" "$pgid" "$stored_fingerprint" ||
+      die "State points at an unowned '$name' process; refusing to kill it."
+    if [ "$stored_fingerprint" = "$fingerprint" ]; then
+      echo "[devrouter-process] '$name' already matches this runtime (PID $pid)."
+      exit 0
+    fi
+
+    echo "[devrouter-process] '$name' runtime changed; restarting owned process group $pgid."
+    stop_process_group "$pid" "$pgid"
+    rm -f "$state_file"
+  else
+    rm -f "$state_file"
+  fi
+fi
+
+unknown_process_exists &&
+  die "Found an unowned '$name' process; refusing to start a duplicate or kill it."
+
+echo "[devrouter-process] Starting '$name' (logs: $log_file)..."
+env DEVROUTER_PROCESS_NAME="$name" \
+  DEVROUTER_PROCESS_FINGERPRINT="$fingerprint" \
+  setsid "$@" 9>&- >"$log_file" 2>&1 </dev/null &
+pid=$!
+pgid="$pid"
+
+for attempt in {1..10}; do
+  if process_owned "$pid" "$pgid" "$fingerprint"; then
+    printf '%s %s %s\n' "$pid" "$pgid" "$fingerprint" >"$state_file.tmp.$BASHPID"
+    mv "$state_file.tmp.$BASHPID" "$state_file"
+    echo "[devrouter-process] '$name' started (PID $pid)."
+    exit 0
+  fi
+  if ! process_alive "$pid"; then
+    die "'$name' exited during startup; see $log_file."
+  fi
+  sleep 1
+done
+
+stop_process_group "$pid" "$pgid" || true
+die "Could not verify ownership of '$name'; stopped it."