@lifeaitools/rdc-skills 0.35.24 → 0.35.26

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.35.24",
+  "version": "0.35.26",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",

package/RELEASE.md

@@ -69,21 +69,63 @@ The public `/health` version must equal the released npm version and its skill
 count must match the packaged catalog. The local installer never restarts or
 deploys that endpoint.
 
-The Vultr host checks out this repository at `/srv/regen/rdc-skills` — it runs
-straight from the checkout (no `npm install`), so `/health`'s `git_sha` comes
-from `bin/rdc-skills-mcp.mjs`'s runtime `git rev-parse HEAD` fallback, NOT a
-stamped `git-sha.json` (that file is `.gitignore`d on purpose — it's a
-pack-time-only artifact for npm-installed copies; see the comment above its
-`.gitignore` entry). `install-systemd.sh` alone does not restart the running
-process. After pulling `master`:
+The Vultr host checks out this repository at `/srv/regen/rdc-skills` and runs the
+server straight from that checkout, with production dependencies installed there
+by `npm ci`. `/health`'s `git_sha` comes from `bin/rdc-skills-mcp.mjs`'s runtime
+`git rev-parse HEAD`, resolved once when the process starts — NOT a stamped
+`git-sha.json` (that file is `.gitignore`d on purpose — it's a pack-time-only
+artifact for npm-installed copies; the updater deletes one if it appears in the
+checkout). `version`, by contrast, is re-read from `package.json` on every
+request, so **only `git_sha` proves the process restarted onto a release.**
+
+**The host follows release tags by itself.** `rdc-skills-mcp-update.timer` runs
+the updater ([`deploy/update-from-tag.sh`](deploy/update-from-tag.sh), installed
+at `/usr/local/libexec/rdc-skills/` so no rollback can delete it) every five
+minutes. The service is only ever restarted onto a **release**: the newest plain
+`vX.Y.Z` tag merged into `master`, or the last release the updater proved serving.
+Untagged commits, pre-releases and tags off `master` are never served — a checkout
+pulled ahead to untagged `master` is moved back to the tag. The updater reinstalls
+dependencies and unit files only when they differ from the last install, restarts
+the MCP, and succeeds only when `/health` reports the release's version **and**
+commit. "Current" is decided by `/health`, never by where `HEAD` is — a run that was
+interrupted converges on the next tick.
+
+A release only moves forward: a tag that is not a descendant of the proved release
+(a higher number put on an older commit) is held off, so rolling back means tagging
+a new, higher release. A release that restarts but never answers is recorded as
+failed in `/var/lib/rdc-skills-update/failed`, the proved release is served again,
+and the failed one is not retried until a newer tag exists. An install or restart
+error says nothing about the release: the proved release is served again and the
+new one is retried next run. A registry that cannot be reached is not counted
+unless it stays unreachable for that release for a whole day; any other install or
+restart error, the third time against the same release, marks it failed. To retry a release marked failed without tagging again, delete its line
+from that file on the host. A host with no history adopts the commit it is already
+serving (if that commit is on `master`) as the proved release before touching
+anything, so the first move has somewhere to go back to. Tracked changes on the
+host, or a commit made on the host, are refused and the service is left as it is.
+So pushing the tag is the whole public MCP deploy — expect it live within about
+five minutes:
 
 ```bash
-git pull --ff-only origin master
-sudo ./deploy/install-systemd.sh        # re-verify/re-enable the unit config
-sudo systemctl restart rdc-skills-mcp.service   # actually load the new commit
-curl -fsS https://rdc-skills.regendevcorp.com/health   # confirm git_sha == new HEAD
+tag=v$(node -p "require('./package.json').version")
+curl -fsS https://rdc-skills.regendevcorp.com/health   # git_sha == the line below
+git rev-list -n 1 "$tag"
+# on the host: journalctl -u rdc-skills-mcp-update.service -n 20
+```
+
+`install-systemd.sh` is the one-time host bootstrap. It installs the units and the
+updater, runs the updater once (which restarts the MCP onto the checked-out release
+and proves it), then enables the timer:
+
+```bash
+cd /srv/regen/rdc-skills
+git fetch --tags origin && git merge --ff-only v<X.Y.Z>
+sudo ./deploy/install-systemd.sh
 ```
 
+Before the timer existed the checkout moved only when someone logged in and
+pulled, and the public catalog sat on 0.35.18 through six releases.
+
 Port `3110` is reserved for this public MCP ingress. Application fleet manifests
 must not claim it.
 

package/deploy/install-systemd.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
+# One-time host bootstrap for the public MCP. From then on the timer keeps the
+# checkout on the newest release tag (deploy/update-from-tag.sh).
+#
+#   cd /srv/regen/rdc-skills
+#   git fetch --tags origin && git merge --ff-only v<X.Y.Z>
+#   sudo ./deploy/install-systemd.sh
 set -euo pipefail
 
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
-unit_source="$repo_root/deploy/systemd/rdc-skills-mcp.service"
-unit_target="/etc/systemd/system/rdc-skills-mcp.service"
+unit_dir="/etc/systemd/system"
+libexec_dir="/usr/local/libexec/rdc-skills"
 
 if [[ "$repo_root" != "/srv/regen/rdc-skills" ]]; then
   echo "rdc-skills must be checked out at /srv/regen/rdc-skills" >&2
@@ -14,9 +20,26 @@ cd "$repo_root"
 # The MCP imports declared runtime dependencies (including express).  A Git
 # checkout alone cannot satisfy those imports after a clean host or dependency
 # cleanup, so install the committed production graph before the unit is enabled.
-npm ci --omit=dev --no-audit --no-fund
+# No install scripts: nothing the server imports needs one, and this runs as root.
+npm ci --omit=dev --no-audit --no-fund --ignore-scripts
 
-install -m 0644 "$unit_source" "$unit_target"
+install -m 0644 deploy/systemd/rdc-skills-mcp.service "$unit_dir/rdc-skills-mcp.service"
+install -m 0644 deploy/systemd/rdc-skills-mcp-update.service "$unit_dir/rdc-skills-mcp-update.service"
+install -m 0644 deploy/systemd/rdc-skills-mcp-update.timer "$unit_dir/rdc-skills-mcp-update.timer"
+install -D -m 0755 deploy/update-from-tag.sh "$libexec_dir/update-from-tag.sh"
 systemctl daemon-reload
-systemctl enable --now rdc-skills-mcp.service
-systemctl --no-pager --full status rdc-skills-mcp.service
+systemctl enable rdc-skills-mcp.service
+
+# `enable --now` does not restart a process that is already running, so an
+# existing host would keep serving the old commit. The updater restarts into the
+# checked-out release and succeeds only when /health proves it; if that release
+# does not come up it returns to the commit that was serving. The timer is
+# enabled either way — the updater's own state decides what the next run does —
+# and the installer exits with the first run's status.
+first_run=0
+systemctl start rdc-skills-mcp-update.service || first_run=$?
+systemctl enable --now rdc-skills-mcp-update.timer
+systemctl --no-pager --full status rdc-skills-mcp.service || true
+systemctl --no-pager list-timers rdc-skills-mcp-update.timer
+journalctl -u rdc-skills-mcp-update.service -n 20 --no-pager || true
+exit "$first_run"

package/deploy/systemd/rdc-skills-mcp-update.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=Keep the public RDC Skills MCP on the newest release tag
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=root
+WorkingDirectory=/srv/regen/rdc-skills
+# A copy outside the checkout: a rollback to a release that predates the
+# updater must not be able to delete the program doing the rollback.
+ExecStart=/usr/local/libexec/rdc-skills/update-from-tag.sh
+# Proved and failed commits, and install hashes — outside the checkout it judges.
+StateDirectory=rdc-skills-update
+TimeoutStartSec=20min

package/deploy/systemd/rdc-skills-mcp-update.timer

@@ -0,0 +1,9 @@
+[Unit]
+Description=Check for a new RDC Skills release every five minutes
+
+[Timer]
+OnBootSec=2min
+OnUnitActiveSec=5min
+
+[Install]
+WantedBy=timers.target

package/deploy/update-from-tag.sh

@@ -0,0 +1,382 @@
+#!/usr/bin/env bash
+# Keep the public MCP on the newest release tag, and prove it is serving it.
+#
+# The tag is the promotion for rdc-skills (RELEASE.md). npm consumers get a tag
+# when the registry does; this is the same act for the one consumer that runs
+# from a git checkout — the public MCP at https://rdc-skills.regendevcorp.com.
+# Before this existed the checkout moved only when someone logged in and pulled,
+# which the fleet's hand-rolled-deploy guard refuses, so the public catalog sat
+# on 0.35.18 through six releases while npm moved on.
+#
+# THE MODEL (classified per .claude/rules/stateful-inspection.md)
+#   identity  a RELEASE: a plain vX.Y.Z tag merged into origin/master, or the
+#             PROVED commit — the last one this updater restarted onto and saw
+#             /health report. On a host with no history, the commit the running
+#             process reports is adopted as proved: it is demonstrably serving.
+#   state     HEAD; the recorded dependency and unit installs; the FAILED set;
+#             the install-error ATTEMPTS against one release.
+#   liveness  /health's git_sha (fixed at process start) and version (re-read
+#             from package.json on every request — so only git_sha proves a
+#             restart took).
+#
+# THE INVARIANT: the service is restarted only onto a release. HEAD is state; it
+# is moved to a release, never served for being checked out. A HEAD that is not
+# a release and not on origin/master (a commit made on the host) is refused and
+# the service is left alone.
+#
+# EACH RUN: desired = the newest tag unless it has FAILED or is not ahead of the
+# proved release, else the proved release. Move HEAD there if needed; if /health
+# already reports it and the installs match, done. Otherwise converge (install
+# what changed, restart, prove):
+#   proved           record it, refresh the updater copy
+#   never answers    the release is bad: record FAILED (never the proved one),
+#                    return to the proved release
+#   install/restart  says nothing about the release, the first two times: return
+#   error            to the proved release and retry next run. The third time
+#                    against the same release it is treated as bad. A registry
+#                    that cannot be reached is not counted — unless it has been
+#                    unreachable for that release for a whole day.
+#
+# Run by rdc-skills-mcp-update.timer from a copy OUTSIDE the checkout
+# (/usr/local/libexec/rdc-skills), refreshed only after a proved move — a
+# rollback to a release that predates this file can never delete the updater.
+# State lives in /var/lib/rdc-skills-update, not in the checkout it judges.
+#
+# Exit codes: 0 serving the newest release · 2 wrong checkout · 3 tracked changes
+# (preserved, never touched) · 4 HEAD is a commit made on the host (refused, service
+# untouched) · 5 the newest release failed and the proved one is serving again ·
+# 6 nothing proved serving this run (retried next run) · 7 the newest release
+# failed before; the proved one is held · 8 serving and proved, but recording it
+# or refreshing the updater copy failed (retried next run) · 9 the newest tag is
+# not ahead of the proved release (a downgrade); the proved one is held.
+#
+# Everything runs from functions called on the last line. Bash reads a script as
+# it executes; by the time main runs, every line it will execute has been read.
+set -euo pipefail
+
+ROOT="${RDC_SKILLS_DEPLOY_ROOT:-/srv/regen/rdc-skills}"
+EXPECTED_ROOT="${RDC_SKILLS_EXPECTED_ROOT:-/srv/regen/rdc-skills}"
+UNIT="rdc-skills-mcp.service"
+UNIT_DIR="${RDC_SKILLS_UNIT_DIR:-/etc/systemd/system}"
+LIBEXEC_DIR="${RDC_SKILLS_LIBEXEC_DIR:-/usr/local/libexec/rdc-skills}"
+STATE_DIR="${RDC_SKILLS_STATE_DIR:-/var/lib/rdc-skills-update}"
+LOCK_FILE="${RDC_SKILLS_LOCK_FILE:-/run/lock/rdc-skills-update.lock}"
+HEALTH_URL="${RDC_SKILLS_HEALTH_URL:-http://127.0.0.1:3110/health}"
+HEALTH_DEADLINE="${RDC_SKILLS_HEALTH_DEADLINE:-120}"
+HEALTH_INTERVAL="${RDC_SKILLS_HEALTH_INTERVAL:-2}"
+HEALTH_SETTLE_ATTEMPTS="${RDC_SKILLS_HEALTH_SETTLE_ATTEMPTS:-3}"
+INSTALL_ERROR_LIMIT="${RDC_SKILLS_INSTALL_ERROR_LIMIT:-3}"
+# How long one release may keep failing to reach the registry before it is judged
+# bad after all (a lockfile `resolved` URL on a host that no longer exists).
+NETWORK_ERROR_WINDOW="${RDC_SKILLS_NETWORK_ERROR_WINDOW:-86400}"
+SYSTEMCTL="${SYSTEMCTL:-systemctl}"
+# Release tags are fetched with force into a namespace this updater owns, so a
+# tag moved or re-created on origin updates here instead of failing the fetch.
+RELEASE_REFS="refs/rdc-release-tags"
+
+log() { printf 'rdc-skills-update: %s\n' "$*"; }
+
+state_get() { cat "$STATE_DIR/$1" 2>/dev/null || true; }
+state_put() { printf '%s\n' "$2" > "$STATE_DIR/$1.tmp" && mv -f "$STATE_DIR/$1.tmp" "$STATE_DIR/$1"; }
+
+# Never fails, and never reads stdin: no arguments hash as empty input.
+hash_files() { { if (($#)); then cat -- "$@" 2>/dev/null || true; fi; } | sha256sum | cut -d' ' -f1; }
+unit_files() { (shopt -s nullglob; printf '%s\n' deploy/systemd/*.service deploy/systemd/*.timer); }
+
+version_at() {
+  git show "$1:package.json" | node -e 'process.stdout.write(JSON.parse(require("fs").readFileSync(0, "utf8")).version)'
+}
+
+health_field() {
+  HEALTH="$1" FIELD="$2" node -e '
+    try { process.stdout.write(String(JSON.parse(process.env.HEALTH)[process.env.FIELD] ?? "")); } catch {}
+  ' 2>/dev/null || true
+}
+health_body() { curl -fsS -m 5 "$HEALTH_URL" 2>/dev/null || true; }
+answers_as() { # <body> <sha> <version>
+  [[ -n "$1" && "$(health_field "$1" git_sha)" == "$2" && "$(health_field "$1" version)" == "$3" ]]
+}
+
+# The first ANSWER decides; only silence is retried — one slow response never
+# restarts a healthy service. Prints the answer (empty when there was none).
+settled_body() {
+  local i body=""
+  for ((i = 1; i <= HEALTH_SETTLE_ATTEMPTS; i++)); do
+    body="$(health_body)"
+    [[ -n "$body" ]] && break
+    ((i < HEALTH_SETTLE_ATTEMPTS)) && sleep "$HEALTH_INTERVAL"
+  done
+  printf '%s' "$body"
+}
+
+wait_serving() { # <sha> <version>: after a restart, until the deadline
+  local end=$((SECONDS + HEALTH_DEADLINE)) body=""
+  while :; do
+    body="$(health_body)"
+    answers_as "$body" "$1" "$2" && return 0
+    ((SECONDS >= end)) && break
+    sleep "$HEALTH_INTERVAL"
+  done
+  log "health at $HEALTH_URL did not report $2 @ ${1:0:7} within ${HEALTH_DEADLINE}s; last: ${body:-<no answer>}"
+  return 1
+}
+
+installs_match() {
+  [[ -d node_modules ]] \
+    && [[ "$(hash_files package-lock.json)" == "$(state_get lock-sha256)" ]] \
+    && [[ "$(hash_files $(unit_files))" == "$(state_get units-sha256)" ]]
+}
+
+held() { # <sha> <version>: /health reports the release and the installs match (serve moved HEAD to it)
+  answers_as "$(settled_body)" "$1" "$2" && installs_match
+}
+
+# converge <sha> <version>: with HEAD at <sha>, install what changed since the
+# last install, restart, and prove it.
+#   0 proved · 1 install or restart error · 2 restarted, but /health never reported it
+#   3 the dependency install could not reach the registry (never counted against a release)
+# Each recorded hash is cleared BEFORE its install and written after, so a run
+# killed halfway is redone rather than trusted. errexit is suspended inside a
+# function called from a condition, so every step checks its own status.
+converge() {
+  local sha="$1" version="$2" lock_hash units_hash units npm_out npm_rc
+  if [[ -e git-sha.json ]]; then
+    # A pack-time stamp outranks `git rev-parse` in the MCP and would pin
+    # /health to whatever commit was packed here, failing every proof.
+    log "removing a stale git-sha.json stamp from the checkout"
+    rm -f git-sha.json || return 1
+  fi
+  lock_hash="$(hash_files package-lock.json)"
+  if [[ ! -d node_modules || "$lock_hash" != "$(state_get lock-sha256)" ]]; then
+    log "installing the locked production dependency graph"
+    state_put lock-sha256 "" || return 1
+    # --ignore-scripts: nothing the server imports needs an install script, and
+    # this runs as root, unattended, within minutes of a tag.
+    npm_rc=0
+    npm_out="$(npm ci --omit=dev --no-audit --no-fund --ignore-scripts 2>&1)" || npm_rc=$?
+    if ((npm_rc != 0)); then
+      printf '%s\n' "$npm_out" | tail -n 5 | sed 's/^/rdc-skills-update:   /'
+      # A registry that cannot be reached says nothing about the release; a
+      # lockfile that cannot install does.
+      if grep -qE '^npm (ERR!|error) (code (E5[0-9]{2}|ETIMEDOUT|ECONNRESET|ECONNREFUSED|EAI_AGAIN|ENOTFOUND|ENETUNREACH|EHOSTUNREACH)|network )' <<<"$npm_out"; then
+        log "npm ci could not reach the registry"
+        return 3
+      fi
+      log "npm ci failed"
+      return 1
+    fi
+    state_put lock-sha256 "$lock_hash" || return 1
+  fi
+  units="$(unit_files)"
+  # shellcheck disable=SC2086 # unit file names carry no spaces
+  units_hash="$(hash_files $units)"
+  if [[ "$units_hash" != "$(state_get units-sha256)" ]]; then
+    log "installing unit files"
+    state_put units-sha256 "" || return 1
+    if [[ -n "$units" ]]; then
+      # shellcheck disable=SC2086
+      install -m 0644 $units "$UNIT_DIR/" || return 1
+    fi
+    "$SYSTEMCTL" daemon-reload || return 1
+    state_put units-sha256 "$units_hash" || return 1
+  fi
+  "$SYSTEMCTL" restart "$UNIT" || { log "restart failed"; return 1; }
+  wait_serving "$sha" "$version" || return 2
+}
+
+is_failed() { [[ -f "$STATE_DIR/failed" ]] && grep -qx "$1" "$STATE_DIR/failed"; }
+mark_failed() { is_failed "$1" || printf '%s\n' "$1" >> "$STATE_DIR/failed"; }
+
+# Install/restart errors counted against one release; any other release resets it.
+bump_attempts() {
+  local sha="$1" recorded count=0
+  recorded="$(state_get attempts)"
+  [[ "${recorded%% *}" == "$sha" ]] && count="${recorded##* }"
+  count=$((count + 1))
+  state_put attempts "$sha $count"
+  printf '%s' "$count"
+}
+
+# Seconds this release has been failing to reach the registry (0 on the first failure).
+network_failing_for() {
+  local sha="$1" recorded now since
+  now="$(date +%s)"
+  recorded="$(state_get network-since)"
+  if [[ "${recorded%% *}" == "$sha" ]]; then
+    since="${recorded##* }"
+  else
+    since="$now"
+    state_put network-since "$sha $now"
+  fi
+  printf '%s' "$((now - since))"
+}
+
+# serve <sha> <version>: move HEAD to a release and make /health prove it.
+# Returns converge's code (0 also when it was already held).
+serve() {
+  local sha="$1" version="$2" rc=0
+  if [[ "$(git rev-parse HEAD)" != "$sha" ]]; then
+    git reset --quiet --hard "$sha" || return 1
+  fi
+  held "$sha" "$version" && return 0
+  log "converging ${sha:0:7} ($version)"
+  converge "$sha" "$version" || rc=$?
+  return "$rc"
+}
+
+main() {
+  if [[ "$ROOT" != "$EXPECTED_ROOT" ]]; then
+    log "refused: checkout is $ROOT, expected $EXPECTED_ROOT"
+    return 2
+  fi
+  mkdir -p "$STATE_DIR"
+  # systemd never overlaps two timer runs; this also covers a run started by hand.
+  if command -v flock >/dev/null 2>&1; then
+    exec 9>"$LOCK_FILE"
+    if ! flock -n 9; then
+      log "another update run holds $LOCK_FILE"
+      return 0
+    fi
+  fi
+  cd "$ROOT"
+
+  local tracked
+  tracked="$(git status --porcelain --untracked-files=no)"
+  if [[ -n "$tracked" ]]; then
+    log "refused: tracked changes in $ROOT — preserved, not updated"
+    printf '%s\n' "$tracked" | sed 's/^/rdc-skills-update:   /'
+    return 3
+  fi
+
+  # Releases are read only from the forced namespace below, so a tag moved on
+  # origin updates there instead of being refused as a clobber (which, with
+  # `--tags` into refs/tags, fails the whole fetch every run). --no-tags keeps
+  # refs/tags out of it entirely.
+  git fetch --quiet --no-tags --prune origin \
+    '+refs/heads/master:refs/remotes/origin/master' \
+    "+refs/tags/v*:$RELEASE_REFS/v*"
+  # Plain vX.Y.Z only: a pre-release or a stray `v*` name is never a release.
+  local tag target=""
+  tag="$(git for-each-ref --merged refs/remotes/origin/master --sort=-v:refname \
+    --format='%(refname:lstrip=2)' "$RELEASE_REFS" \
+    | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1 || true)"
+  [[ -n "$tag" ]] && target="$(git rev-parse "$RELEASE_REFS/$tag^{commit}")"
+
+  local proved
+  proved="$(state_get proved)"
+  if [[ -z "$proved" ]]; then
+    # No history: adopt what is demonstrably serving, so a bad first release has
+    # somewhere to go back to — recorded BEFORE anything is restarted.
+    local running
+    running="$(health_field "$(settled_body)" git_sha)"
+    # Only a commit on origin/master: adopting a host-made commit would let the
+    # move below reset it off every branch.
+    if [[ -n "$running" ]] && git cat-file -e "$running^{commit}" 2>/dev/null \
+      && git merge-base --is-ancestor "$running" refs/remotes/origin/master; then
+      state_put proved "$running"
+      proved="$running"
+      log "adopted the serving commit ${running:0:7} as the proved release"
+    fi
+  fi
+
+  # A release only moves forward: a tag that is not the proved commit or a
+  # descendant of it (a higher number put on an older commit) would downgrade the
+  # public MCP. Rolling back is a new, higher tag — the tag is the promotion.
+  local desired="" holding=""
+  if [[ -n "$target" && -n "$proved" && "$target" != "$proved" ]] \
+    && ! git merge-base --is-ancestor "$proved" "$target"; then
+    desired="$proved"
+    holding="behind"
+  elif [[ -n "$target" ]] && ! is_failed "$target"; then
+    desired="$target"
+  elif [[ -n "$proved" ]]; then
+    desired="$proved"
+    [[ -n "$target" ]] && holding="failed"
+  fi
+  if [[ -z "$desired" ]]; then
+    if [[ -n "$target" ]]; then
+      log "$tag failed its health proof and there is no proved release to serve"
+    else
+      log "no release tag reachable from origin/master, and no proved release"
+    fi
+    return 6
+  fi
+
+  # HEAD is state, but a commit made ON the host is work that exists nowhere else:
+  # never discard it, and never serve it.
+  local head
+  head="$(git rev-parse HEAD)"
+  if [[ "$head" != "$desired" && "$head" != "$proved" && "$head" != "$target" ]] \
+    && ! git merge-base --is-ancestor "$head" refs/remotes/origin/master; then
+    log "refused: HEAD ${head:0:7} is a commit made on this host (not on origin/master) — preserved; the service is left as it is"
+    return 4
+  fi
+
+  local version rc=0
+  version="$(version_at "$desired")"
+  serve "$desired" "$version" || rc=$?
+  local name="${tag:-release}"
+  [[ "$desired" != "$target" ]] && name="${desired:0:7}"
+
+  if ((rc == 0)); then
+    state_put attempts "" || true
+    state_put network-since "" || true
+    if [[ "$(state_get proved)" != "$desired" ]] && ! state_put proved "$desired"; then
+      log "serving $name (${desired:0:7}), but recording it as proved failed"
+      return 8
+    fi
+    # The updater copy follows the newest release only — a held older release may
+    # predate this file. Compared by content, so a failed refresh is retried.
+    if [[ "$desired" == "$target" ]] && ! cmp -s deploy/update-from-tag.sh "$LIBEXEC_DIR/update-from-tag.sh"; then
+      if ! install -D -m 0755 deploy/update-from-tag.sh "$LIBEXEC_DIR/update-from-tag.sh"; then
+        log "serving $name (${desired:0:7}), but refreshing the updater copy in $LIBEXEC_DIR failed"
+        return 8
+      fi
+    fi
+    if [[ "$holding" == failed ]]; then
+      log "holding ${desired:0:7}: $tag (${target:0:7}) failed its health proof before; waiting for a newer tag"
+      return 7
+    fi
+    if [[ "$holding" == behind ]]; then
+      log "holding ${desired:0:7}: the newest tag $tag (${target:0:7}) is not ahead of the proved release; waiting for a newer tag"
+      return 9
+    fi
+    log "current at $name (${desired:0:7})"
+    return 0
+  fi
+
+  # Not proved. The proved release itself is never marked failed: it served.
+  local bad=0
+  if [[ "$desired" != "$proved" ]]; then
+    if ((rc == 2)); then
+      bad=1
+    elif ((rc == 3)); then
+      if (( $(network_failing_for "$desired") >= NETWORK_ERROR_WINDOW )); then
+        log "installing $name has failed to reach the registry for over ${NETWORK_ERROR_WINDOW}s; treating it as a bad release"
+        bad=1
+      else
+        log "the registry could not be reached installing $name; retrying next run (not counted)"
+      fi
+    elif (( $(bump_attempts "$desired") >= INSTALL_ERROR_LIMIT )); then
+      log "install or restart error on $name for the ${INSTALL_ERROR_LIMIT}th run; treating it as a bad release"
+      bad=1
+    else
+      log "install or restart error on $name; retrying next run"
+    fi
+    ((bad)) && mark_failed "$desired"
+  fi
+
+  if [[ -n "$proved" && "$desired" != "$proved" ]]; then
+    log "returning to the proved release ${proved:0:7}"
+    local back_rc=0
+    serve "$proved" "$(version_at "$proved")" || back_rc=$?
+    if ((back_rc == 0)); then
+      ((bad)) && { log "$name failed; the proved release is serving again"; return 5; }
+      return 6
+    fi
+    log "the proved release ${proved:0:7} could not be proved serving either"
+  fi
+  return 6
+}
+
+main "$@"; exit $?

package/git-sha.json

@@ -0,0 +1,3 @@
+{
+  "sha": "31c8a8246ec68e424893534d7da36166f52a6f73"
+}

package/guides/work-contract.md

@@ -69,6 +69,17 @@ A refused proof is recorded as exit 126 and **never runs**. Prove an action by
 observing its result: a push with `git merge-base --is-ancestor HEAD origin/<branch>`,
 a deploy with a read-only probe, a file with `test -f`.
 
+**A proof is a POSIX shell command, on every engine.** `rdc-work` runs it with
+`-c '<proof>'` in Git Bash on Windows and in `/bin/sh` everywhere else (dash on
+Debian and Ubuntu) — whatever shell the agent itself uses. Write plain `sh`: a
+bash-only form (`[[ ]]`, `$RANDOM`, arrays) passes on Windows and fails on Linux.
+`$var`, `"…"` and backticks are expanded by that shell before any program sees
+them. A PowerShell check goes inside single quotes, where POSIX
+expands nothing: `pwsh -NoProfile -Command '(Get-Service x).Status -eq "Running"'`
+— and since that prints `True` or `False` and exits 0 either way, end it with
+`| grep -qx True`, or put the check in a script that exits non-zero, and prove with
+`pwsh -NoProfile -File check.ps1`.
+
 ## Tier — the agent picks
 
 | `--type` | tier | also |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.35.24",
+  "version": "0.35.26",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",
@@ -55,7 +55,8 @@
     "test:channel-formatter:remote": "node tests/channel-formatter.contract.test.mjs --remote",
     "test:brochure": "node tests/rdc-brochure.test.mjs",
     "mcp": "node bin/rdc-skills-mcp.mjs",
-    "prepack": "node scripts/prepack.mjs"
+    "prepack": "node scripts/prepack.mjs",
+    "test:deploy": "node tests/deploy-updater.test.mjs"
   },
   "dependencies": {
     "@lifeaitools/clauth-surface-sdk": "^0.1.0",

package/scripts/install-rdc-skills.js

@@ -1277,7 +1277,14 @@ async function main() {
   const pkg     = readJson(path.join(repoRoot, 'package.json'));
   const version = pkg.version || '0.7.0';
   let   gitSha  = '';
-  try { gitSha = execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); } catch {}
+  if (fs.existsSync(path.join(repoRoot, '.git'))) {
+    try { gitSha = execSync('git rev-parse HEAD', { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); } catch {}
+  } else {
+    // An npm-installed package has no .git — and `git rev-parse` would walk up into
+    // whatever repository encloses it. The commit is the pack-time stamp instead.
+    gitSha = String(readJson(path.join(repoRoot, 'git-sha.json'))?.sha || '');
+    if (gitSha === 'unknown') gitSha = '';
+  }
 
   // 0.5a. User-skills cleanup — remove any rdc: skills from ~/.claude/skills/user/
   // (older installer versions wrote there; plugin cache is the only authoritative source)

package/tests/deploy-updater.test.mjs

@@ -0,0 +1,608 @@
+// deploy/update-from-tag.sh — the public MCP follows release tags by itself.
+//
+// Behavioral: a real origin, a real deploy clone, and stub systemctl/npm/curl
+// that model the running MCP the way it actually behaves — `git_sha` is fixed
+// when the process starts, `version` is re-read from package.json on every
+// request. So a restart that did not take, a release that never comes up, and a
+// checkout moved without a restart are each observable exactly as on the host,
+// and every outcome is proved by the commit the checkout ends on and what
+// /health reports, not by a log line.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const UPDATER = path.join(REPO_ROOT, 'deploy', 'update-from-tag.sh');
+const read = (relative) => fs.readFileSync(path.join(REPO_ROOT, relative), 'utf8');
+
+function bashExecutable() {
+  if (process.platform !== 'win32') return 'bash';
+  // `bash` on a Windows PATH can be WSL's System32 shim, which cannot see these paths.
+  const git = 'C:/Program Files/Git/bin/bash.exe';
+  return fs.existsSync(git) ? git : 'bash';
+}
+const BASH = bashExecutable();
+const slash = (p) => p.replace(/\\/g, '/');
+// Git for Windows' bash.exe prepends /mingw64/bin and /usr/bin, so the stubs go
+// on PATH from inside the shell, in its own path form.
+const posix = (p) => (process.platform === 'win32' ? slash(p).replace(/^([A-Za-z]):/, (_, d) => `/${d.toLowerCase()}`) : p);
+
+function sandbox() {
+  const dir = fs.realpathSync.native(fs.mkdtempSync(path.join(os.tmpdir(), 'rdc-skills-updater-')));
+  const gitConfig = path.join(dir, 'gitconfig');
+  fs.writeFileSync(gitConfig, '[user]\n\tname = updater-test\n\temail = updater-test@example.invalid\n[init]\n\tdefaultBranch = master\n');
+  const env = { ...process.env, GIT_CONFIG_GLOBAL: gitConfig, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' };
+  const run = (cwd, args) => {
+    const r = spawnSync('git', args, { cwd, env, encoding: 'utf8' });
+    assert.equal(r.status, 0, `git ${args.join(' ')} failed: ${r.stderr}`);
+    return r.stdout.trim();
+  };
+
+  const origin = path.join(dir, 'origin.git');
+  const author = path.join(dir, 'author');
+  const deploy = path.join(dir, 'deploy');
+  const units = path.join(dir, 'units');
+  const libexec = path.join(dir, 'libexec');
+  const stateDir = path.join(dir, 'state');
+  const stubs = path.join(dir, 'stubs');
+  const svc = path.join(dir, 'svc');
+  for (const d of [author, units, stubs, svc]) fs.mkdirSync(d, { recursive: true });
+  run(dir, ['init', '--bare', '-q', origin]);
+  run(author, ['init', '-q']);
+  run(author, ['remote', 'add', 'origin', slash(origin)]);
+
+  const write = (relative, body) => {
+    const file = path.join(author, relative);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, body);
+  };
+  // release(version, { tag }) — tag: true → `v<version>`, a string → that name, false → untagged.
+  const release = (version, { lock = `lock-${version}`, unit = 'unit-v1', broken = false, tag = true, branch = 'master' } = {}) => {
+    write('.gitignore', 'node_modules/\ngit-sha.json\n');
+    write('package.json', JSON.stringify({ name: 'rdc-skills-fixture', version }, null, 2) + '\n');
+    write('package-lock.json', JSON.stringify({ marker: lock }) + '\n');
+    write('deploy/systemd/rdc-skills-mcp.service', `# ${unit}\n`);
+    write('deploy/update-from-tag.sh', `# updater as of ${version}\n`);
+    if (broken) write('BROKEN', 'this release never answers /health\n');
+    else fs.rmSync(path.join(author, 'BROKEN'), { force: true });
+    run(author, ['add', '-A']);
+    run(author, ['commit', '-q', '--allow-empty', '-m', `release ${version}`]);
+    const name = tag === true ? `v${version}` : tag;
+    if (name) run(author, ['tag', name]);
+    run(author, ['push', '-q', 'origin', `HEAD:${branch}`, ...(name ? [`refs/tags/${name}`] : [])]);
+    return run(author, ['rev-parse', 'HEAD']);
+  };
+
+  const stub = (name, body) => {
+    const file = path.join(stubs, name);
+    fs.writeFileSync(file, `#!/usr/bin/env bash\n${body}\n`);
+    fs.chmodSync(file, 0o755);
+  };
+  const calls = path.join(dir, 'calls.log');
+  const started = path.join(svc, 'started-sha');
+  // restart: the process starts on whatever commit the checkout holds — unless
+  // this release is BROKEN (it never answers), or the restart silently does not
+  // take (svc/no-restart), in which case the old process keeps running.
+  stub('systemctl', [
+    `echo "systemctl $*" >> "${slash(calls)}"`,
+    'if [[ "$1" == restart ]]; then',
+    // svc/restart-fail-once: the restart stops the old process and fails to start.
+    `  if [[ -f "${slash(svc)}/restart-fail-once" ]]; then rm -f "${slash(svc)}/restart-fail-once" "${slash(started)}"; exit 1; fi`,
+    `  [[ -f "${slash(svc)}/no-restart" ]] && exit 0`,
+    `  if [[ -f "${slash(deploy)}/BROKEN" ]]; then rm -f "${slash(started)}"; exit 0; fi`,
+    `  git -C "${slash(deploy)}" rev-parse HEAD > "${slash(started)}"`,
+    'fi',
+  ].join('\n'));
+  // npm: svc/npm-fail fails every install (a registry outage); svc/npm-fail-once fails one.
+  stub('npm', [
+    `echo "npm $*" >> "${slash(calls)}"`,
+    `if [[ -f "${slash(svc)}/npm-fail" ]]; then echo "npm error code ETIMEDOUT" >&2; echo "npm error network request to https://registry.npmjs.org failed" >&2; exit 1; fi`,
+    // A release whose own lockfile can never install.
+    'if grep -q uninstallable package-lock.json; then echo "npm error code ETARGET" >&2; echo "npm error notarget No matching version found for $(cat package-lock.json)" >&2; exit 1; fi',
+    `if [[ -f "${slash(svc)}/npm-fail-once" ]]; then rm -f "${slash(svc)}/npm-fail-once"; echo "npm error code EINTEGRITY" >&2; exit 1; fi`,
+    'rm -rf node_modules; mkdir -p node_modules',
+  ].join('\n'));
+  // /health: git_sha fixed at process start; version read from disk per request.
+  // svc/curl-fail-once: one request times out (a slow answer).
+  stub('curl', [
+    `if [[ -f "${slash(svc)}/curl-fail-once" ]]; then rm -f "${slash(svc)}/curl-fail-once"; exit 28; fi`,
+    `[[ -f "${slash(started)}" ]] || exit 7`,
+    `ver="$(node -p "require('fs').readFileSync('${slash(deploy)}/package.json','utf8').match(/\\"version\\": \\"([^\\"]+)/)[1]")"`,
+    `printf '{"status":"ok","version":"%s","git_sha":"%s"}' "$ver" "$(tr -d '\\r\\n' < "${slash(started)}")"`,
+  ].join('\n'));
+
+  const updaterEnv = (overrides = {}) => ({
+    ...env,
+    RDC_TEST_STUBS: posix(stubs),
+    RDC_TEST_UPDATER: slash(UPDATER),
+    RDC_SKILLS_DEPLOY_ROOT: slash(deploy),
+    RDC_SKILLS_EXPECTED_ROOT: slash(deploy),
+    RDC_SKILLS_UNIT_DIR: slash(units),
+    RDC_SKILLS_LIBEXEC_DIR: slash(libexec),
+    RDC_SKILLS_STATE_DIR: slash(stateDir),
+    RDC_SKILLS_LOCK_FILE: slash(path.join(dir, 'update.lock')),
+    RDC_SKILLS_HEALTH_URL: 'http://127.0.0.1:1/health',
+    RDC_SKILLS_HEALTH_DEADLINE: '0',
+    RDC_SKILLS_HEALTH_INTERVAL: '0',
+    ...overrides,
+  });
+  const update = (overrides) => {
+    const r = spawnSync(BASH, ['-c', 'PATH="$RDC_TEST_STUBS:$PATH" exec bash "$RDC_TEST_UPDATER"'], { env: updaterEnv(overrides), encoding: 'utf8', input: '' });
+    return { status: r.status, out: `${r.stdout}${r.stderr}` };
+  };
+  const clearCalls = () => fs.rmSync(calls, { force: true });
+  const cloneOnly = () => run(dir, ['clone', '-q', '--branch', 'master', slash(origin), slash(deploy)]);
+  // The service as an operator left it: started by hand on whatever is checked out.
+  const startService = () => {
+    const r = spawnSync(BASH, ['-c', `"${posix(path.join(stubs, 'systemctl'))}" restart rdc-skills-mcp.service`], { env: updaterEnv(), encoding: 'utf8' });
+    assert.equal(r.status, 0, r.stderr);
+    clearCalls();
+  };
+  // A host brought up by the bootstrap: cloned, then converged and proved once.
+  const bootstrap = () => {
+    cloneOnly();
+    const r = update();
+    assert.equal(r.status, 0, `bootstrap did not converge: ${r.out}`);
+    clearCalls();
+    return r;
+  };
+  const head = () => run(deploy, ['rev-parse', 'HEAD']);
+  const servingSha = () => (fs.existsSync(started) ? fs.readFileSync(started, 'utf8').trim() : null);
+  const callLog = () => (fs.existsSync(calls) ? fs.readFileSync(calls, 'utf8') : '');
+  const restarts = () => (callLog().match(/systemctl restart/g) || []).length;
+  const cleanup = () => fs.rmSync(dir, { recursive: true, force: true });
+  const failedList = () => {
+    const f = path.join(stateDir, 'failed');
+    return fs.existsSync(f) ? fs.readFileSync(f, 'utf8').split('\n').filter(Boolean) : [];
+  };
+  return { release, bootstrap, cloneOnly, startService, update, head, servingSha, callLog, restarts, clearCalls, failedList, run, deploy, author, origin, units, libexec, svc, started, cleanup };
+}
+
+test('a fresh checkout converges on first run: installs, restarts, and proves the tag', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('1.0.0');
+  s.run(path.dirname(s.deploy), ['clone', '-q', '--branch', 'master', slash(s.origin), slash(s.deploy)]);
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.servingSha(), v1, 'the service was restarted onto the tag');
+  assert.match(s.callLog(), /npm ci --omit=dev --no-audit --no-fund --ignore-scripts/);
+  assert.equal(fs.readFileSync(path.join(s.libexec, 'update-from-tag.sh'), 'utf8'), '# updater as of 1.0.0\n',
+    'the proved release refreshed the updater copy outside the checkout');
+});
+
+test('a proved host at the newest tag is left alone', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0');
+  s.bootstrap();
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.match(r.out, /current at v1\.0\.0/);
+  assert.equal(s.callLog(), '', 'nothing installed, nothing restarted');
+});
+
+test('a new tag is fast-forwarded, reinstalled when the lock moved, restarted, and proved', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.9.0');
+  s.bootstrap();
+  // v1.10.0 sorts BEFORE v1.9.0 lexically; the updater must pick it by version.
+  const v110 = s.release('1.10.0');
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.head(), v110);
+  assert.equal(s.servingSha(), v110);
+  assert.match(s.callLog(), /npm ci/);
+  assert.equal(fs.readFileSync(path.join(s.libexec, 'update-from-tag.sh'), 'utf8'), '# updater as of 1.10.0\n');
+});
+
+test('a lock file that did not change is not reinstalled', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('2.0.0', { lock: 'same' });
+  s.bootstrap();
+  const v201 = s.release('2.0.1', { lock: 'same' });
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.servingSha(), v201);
+  assert.doesNotMatch(s.callLog(), /npm ci/);
+});
+
+test('an untagged commit on master is not deployed — the tag is the promotion', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('1.0.0');
+  s.bootstrap();
+  s.release('1.0.1', { tag: false });
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.head(), v1);
+});
+
+test('a newer release tag that is not on master is not deployed', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('1.0.0');
+  s.bootstrap();
+  s.release('9.0.0', { branch: 'side' });
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.head(), v1);
+  assert.equal(s.servingSha(), v1);
+});
+
+test('pre-release and stray v* tags are never served and never outrank a release', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v3 = s.release('3.0.0');
+  s.bootstrap();
+  s.release('3.1.0-rc.1', { tag: 'v3.1.0-rc.1' });
+  s.release('3.1.0-wip', { tag: 'v99-test' });
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.match(r.out, /current at v3\.0\.0/, 'v99-test and v3.1.0-rc.1 both sort above v3.0.0 and are ignored');
+  assert.equal(s.servingSha(), v3, 'still serving the last plain release');
+});
+
+test('a release that never answers is rolled back, then skipped until a newer tag', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('3.0.0');
+  s.bootstrap();
+  s.release('3.1.0', { broken: true });
+
+  const first = s.update();
+  assert.equal(first.status, 5, first.out);
+  assert.equal(s.head(), good, 'checkout ends on the release that answered');
+  assert.equal(s.servingSha(), good, '/health proves the rollback took');
+
+  s.clearCalls();
+  const again = s.update();
+  assert.equal(again.status, 7, again.out);
+  assert.equal(s.restarts(), 0, 'a failed release is not retried every tick');
+  assert.equal(s.head(), good);
+
+  const fixed = s.release('3.2.0');
+  const next = s.update();
+  assert.equal(next.status, 0, next.out);
+  assert.equal(s.servingSha(), fixed);
+});
+
+test('an install outage is not a bad release: nothing is recorded, and the release ships once the outage ends', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('2.0.0');
+  s.bootstrap();
+  const next = s.release('2.1.0');
+  fs.writeFileSync(path.join(s.svc, 'npm-fail'), '');
+  // Longer than the install-error limit: a registry outage is never counted.
+  for (let i = 0; i < 4; i += 1) {
+    const during = s.update();
+    assert.equal(during.status, 6, during.out);
+  }
+  assert.equal(s.head(), good, 'the checkout is back on the release that was serving');
+  assert.equal(s.servingSha(), good);
+  assert.deepEqual(s.failedList(), [], 'an outage says nothing about the release');
+
+  fs.rmSync(path.join(s.svc, 'npm-fail'));
+  const after = s.update();
+  assert.equal(after.status, 0, after.out);
+  assert.equal(s.servingSha(), next);
+});
+
+test('a release that never reaches the registry is judged bad once the network-error window passes', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('2.0.0');
+  s.bootstrap();
+  const next = s.release('2.1.0', { lock: 'network-only' });
+  fs.writeFileSync(path.join(s.svc, 'npm-fail'), '');
+  const r = s.update({ RDC_SKILLS_NETWORK_ERROR_WINDOW: '0' });
+  assert.equal(r.status, 6, r.out); // bad, but its own return to 2.0.0 hits the same outage
+  assert.deepEqual(s.failedList(), [next]);
+  assert.equal(s.servingSha(), good);
+});
+
+test('only npm\'s own error lines count as a network failure', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('2.0.0');
+  s.bootstrap();
+  // A lockfile problem whose message merely mentions a network-ish package name.
+  const next = s.release('2.1.0', { lock: 'uninstallable network-utils' });
+  const statuses = [s.update(), s.update(), s.update()].map((r) => r.status);
+  assert.deepEqual(statuses, [6, 6, 5], 'counted like any install error');
+  assert.deepEqual(s.failedList(), [next]);
+});
+
+test('a one-off install failure is retried on the next run, not skipped until a newer tag', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('2.0.0');
+  s.bootstrap();
+  const next = s.release('2.1.0');
+  fs.writeFileSync(path.join(s.svc, 'npm-fail-once'), '');
+  const first = s.update();
+  assert.equal(first.status, 6, first.out);
+  assert.equal(s.servingSha(), good, 'the rollback reinstalled and restarted the previous release');
+  const second = s.update();
+  assert.equal(second.status, 0, second.out);
+  assert.equal(s.servingSha(), next);
+  assert.deepEqual(s.failedList(), []);
+});
+
+test('bootstrap with no history: a bad release returns to the commit that was serving', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const serving = s.release('1.0.0');
+  s.cloneOnly();
+  s.startService();
+  const bad = s.release('1.1.0', { broken: true });
+  // The operator's bootstrap step: fast-forward the checkout to the new tag.
+  s.run(s.deploy, ['fetch', '-q', '--tags', 'origin']);
+  s.run(s.deploy, ['merge', '-q', '--ff-only', 'v1.1.0']);
+
+  const first = s.update();
+  assert.equal(first.status, 5, first.out);
+  assert.equal(s.head(), serving);
+  assert.equal(s.servingSha(), serving, '/health proves the host is back on what it served before');
+
+  s.clearCalls();
+  for (let i = 0; i < 2; i += 1) {
+    const again = s.update();
+    assert.equal(again.status, 7, again.out);
+  }
+  assert.equal(s.restarts(), 0, 'a held, healthy release is not restarted');
+  assert.deepEqual(s.failedList(), [bad], 'recorded once, however many runs');
+});
+
+test('a bad release with nothing to return to fails every run, and is recorded once', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0', { broken: true });
+  s.cloneOnly(); // never served anything: no history, and /health does not answer
+  const bad = s.head();
+  for (let i = 0; i < 3; i += 1) {
+    const r = s.update();
+    assert.equal(r.status, 6, r.out);
+  }
+  assert.deepEqual(s.failedList(), [bad]);
+});
+
+test('a skipped release still holds what is checked out: a service that died is brought back', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('3.0.0');
+  s.bootstrap();
+  s.release('3.1.0', { broken: true });
+  assert.equal(s.update().status, 5);
+  fs.rmSync(s.started); // the process crashed after the rollback
+  const r = s.update();
+  assert.equal(r.status, 7, r.out);
+  assert.equal(s.servingSha(), good);
+  assert.equal(s.restarts() > 0, true);
+});
+
+test('the proved release is never marked failed, even when it does not come back up', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0');
+  s.bootstrap();
+  fs.rmSync(s.started); // it crashed
+  fs.writeFileSync(path.join(s.svc, 'no-restart'), ''); // and the restart does not take
+  const r = s.update();
+  assert.equal(r.status, 6, r.out);
+  assert.deepEqual(s.failedList(), [], 'it served before; a slow or broken host is not a bad release');
+});
+
+test('one slow /health answer does not restart a healthy service', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0');
+  s.bootstrap();
+  fs.writeFileSync(path.join(s.svc, 'curl-fail-once'), '');
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.match(r.out, /current at v1\.0\.0/);
+  assert.equal(s.restarts(), 0);
+});
+
+test('a restart that silently does not take is not reported as a deploy', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('4.0.0');
+  s.bootstrap();
+  s.release('4.1.0');
+  fs.writeFileSync(path.join(s.svc, 'no-restart'), '');
+  const r = s.update();
+  assert.notEqual(r.status, 0, r.out);
+  assert.equal(s.servingSha(), v1, 'the old process is still the one serving');
+  assert.equal(s.head(), v1, 'the checkout is back on what is actually running');
+});
+
+test('a checkout moved without a restart (an interrupted run) converges instead of reading as current', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('5.0.0');
+  s.bootstrap();
+  const v2 = s.release('5.1.0');
+  s.run(s.deploy, ['fetch', '-q', 'origin']);
+  s.run(s.deploy, ['reset', '-q', '--hard', v2]);
+  assert.equal(s.servingSha(), v1, 'precondition: the service never restarted');
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.match(r.out, /converging/);
+  assert.match(s.callLog(), /npm ci/, 'the lock moved with the interrupted checkout, so it is reinstalled');
+  assert.equal(s.servingSha(), v2);
+});
+
+test('a tag moved on origin does not block later releases', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('6.0.0');
+  s.bootstrap();
+  // Re-created on an unrelated commit: not a fast-forward of where it was, so
+  // only a forced fetch can follow it.
+  const unrelated = s.run(s.author, ['commit-tree', 'HEAD^{tree}', '-m', 'v6.0.0 re-created elsewhere']);
+  s.run(s.author, ['tag', '-f', 'v6.0.0', unrelated]);
+  s.run(s.author, ['push', '-q', '-f', 'origin', 'refs/tags/v6.0.0']);
+  const v61 = s.release('6.1.0');
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.servingSha(), v61);
+});
+
+test('tracked changes on the host are preserved and nothing moves', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('7.0.0');
+  s.bootstrap();
+  s.release('7.1.0');
+  fs.appendFileSync(path.join(s.deploy, 'package.json'), '\n');
+  const r = s.update();
+  assert.equal(r.status, 3, r.out);
+  assert.equal(s.head(), v1);
+  assert.match(fs.readFileSync(path.join(s.deploy, 'package.json'), 'utf8'), /\n\n$/, 'the local edit survives');
+  assert.equal(s.callLog(), '');
+});
+
+test('a host commit that the tag does not descend from is refused, not overwritten', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('8.0.0');
+  s.bootstrap();
+  s.release('8.1.0');
+  s.run(s.deploy, ['commit', '-q', '--allow-empty', '-m', 'hotfix made on the host']);
+  const local = s.head();
+  const r = s.update();
+  assert.equal(r.status, 4, r.out);
+  assert.equal(s.head(), local, 'the host commit is preserved');
+  assert.notEqual(s.servingSha(), local, 'and never served');
+  assert.equal(s.restarts(), 0, 'the service is left as it is');
+});
+
+test('a higher tag on an older commit is not a release: the proved one is held, and a real newer tag ships', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const old = s.release('1.0.0');
+  const current = s.release('2.0.0');
+  s.bootstrap();
+  s.run(s.author, ['tag', 'v2.0.1', old]);
+  s.run(s.author, ['push', '-q', 'origin', 'refs/tags/v2.0.1']);
+  const r = s.update();
+  assert.equal(r.status, 9, r.out);
+  assert.equal(s.servingSha(), current, 'never downgraded');
+  assert.equal(s.restarts(), 0);
+  const next = s.release('3.0.0');
+  const after = s.update();
+  assert.equal(after.status, 0, after.out);
+  assert.equal(s.servingSha(), next);
+});
+
+test('with no history, a service running a host-made commit is not adopted, and the commit is kept', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0');
+  s.cloneOnly();
+  s.run(s.deploy, ['commit', '-q', '--allow-empty', '-m', 'made on the host']);
+  const local = s.head();
+  s.startService();
+  s.release('1.1.0');
+  const r = s.update();
+  assert.equal(r.status, 4, r.out);
+  assert.doesNotMatch(r.out, /adopted/);
+  assert.equal(s.head(), local);
+  assert.equal(s.servingSha(), local, 'the service is left as it is');
+});
+
+test('a failed refresh of the updater copy is reported, and retried until it lands', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('1.0.0');
+  s.bootstrap();
+  s.release('1.1.0');
+  const blocked = path.join(s.svc, 'not-a-directory');
+  fs.writeFileSync(blocked, '');
+  const first = s.update({ RDC_SKILLS_LIBEXEC_DIR: slash(path.join(blocked, 'libexec')) });
+  assert.equal(first.status, 8, first.out);
+  const second = s.update();
+  assert.equal(second.status, 0, second.out);
+  assert.equal(fs.readFileSync(path.join(s.libexec, 'update-from-tag.sh'), 'utf8'), '# updater as of 1.1.0\n');
+});
+
+test('a pull to untagged master is moved back to the release, not served', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const v1 = s.release('1.0.0', { lock: 'same' });
+  s.bootstrap();
+  const untagged = s.release('1.0.1', { lock: 'same', tag: false });
+  // The old manual procedure: git pull --ff-only origin master.
+  s.run(s.deploy, ['fetch', '-q', 'origin']);
+  s.run(s.deploy, ['merge', '-q', '--ff-only', untagged]);
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(s.head(), v1);
+  assert.equal(s.servingSha(), v1);
+  assert.equal(s.restarts(), 0, 'it was still serving the release; only the checkout moved back');
+});
+
+test('a release whose lockfile never installs is retried twice, then treated as bad', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const good = s.release('2.0.0');
+  s.bootstrap();
+  const broken = s.release('2.1.0', { lock: 'uninstallable' });
+  const statuses = [s.update(), s.update(), s.update()].map((r) => r.status);
+  assert.deepEqual(statuses, [6, 6, 5]);
+  assert.equal(s.servingSha(), good);
+  assert.deepEqual(s.failedList(), [broken]);
+  s.clearCalls();
+  const held = s.update();
+  assert.equal(held.status, 7, held.out);
+  assert.equal(s.restarts(), 0);
+  assert.doesNotMatch(s.callLog(), /npm ci/);
+});
+
+test('bootstrap: a restart that fails on the new release returns to the adopted serving commit', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  const serving = s.release('1.0.0');
+  s.cloneOnly();
+  s.startService();
+  const next = s.release('1.1.0');
+  s.run(s.deploy, ['fetch', '-q', '--tags', 'origin']);
+  s.run(s.deploy, ['merge', '-q', '--ff-only', 'v1.1.0']);
+  fs.writeFileSync(path.join(s.svc, 'restart-fail-once'), '');
+  const first = s.update();
+  assert.equal(first.status, 6, first.out);
+  assert.equal(s.servingSha(), serving, 'the way back survived the failed restart');
+  const second = s.update();
+  assert.equal(second.status, 0, second.out);
+  assert.equal(s.servingSha(), next);
+});
+
+test('changed unit files are installed and systemd reloaded', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('9.0.0', { unit: 'unit-v1' });
+  s.bootstrap();
+  s.release('9.1.0', { unit: 'unit-v2' });
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.match(fs.readFileSync(path.join(s.units, 'rdc-skills-mcp.service'), 'utf8'), /unit-v2/);
+  assert.match(s.callLog(), /systemctl daemon-reload/);
+});
+
+test('a stale git-sha.json stamp in the checkout is removed so the proof can pass', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('10.0.0');
+  s.bootstrap();
+  const v2 = s.release('10.1.0');
+  fs.writeFileSync(path.join(s.deploy, 'git-sha.json'), '{"sha":"0000000"}\n');
+  const r = s.update();
+  assert.equal(r.status, 0, r.out);
+  assert.equal(fs.existsSync(path.join(s.deploy, 'git-sha.json')), false);
+  assert.equal(s.servingSha(), v2);
+});
+
+test('the updater refuses any checkout other than the host path', (t) => {
+  const s = sandbox(); t.after(s.cleanup);
+  s.release('11.0.0');
+  s.bootstrap();
+  const r = s.update({ RDC_SKILLS_EXPECTED_ROOT: '/srv/regen/rdc-skills' });
+  assert.equal(r.status, 2, r.out);
+});
+
+test('the units and installer run the updater from outside the checkout', () => {
+  const timer = read('deploy/systemd/rdc-skills-mcp-update.timer');
+  const service = read('deploy/systemd/rdc-skills-mcp-update.service');
+  const installer = read('deploy/install-systemd.sh');
+  const updater = read('deploy/update-from-tag.sh');
+  assert.match(timer, /OnUnitActiveSec=/);
+  assert.doesNotMatch(timer, /Persistent=/, 'Persistent= only applies to OnCalendar=');
+  assert.match(service, /Type=oneshot/);
+  assert.match(service, /^ExecStart=\/usr\/local\/libexec\/rdc-skills\/update-from-tag\.sh$/m);
+  assert.match(service, /^StateDirectory=rdc-skills-update$/m);
+  assert.match(installer, /install -D -m 0755 deploy\/update-from-tag\.sh "\$libexec_dir\/update-from-tag\.sh"/);
+  assert.match(installer, /systemctl start rdc-skills-mcp-update\.service/, 'the bootstrap restarts into the release and proves it');
+  assert.match(installer, /systemctl enable --now rdc-skills-mcp-update\.timer/);
+  assert.match(installer, /--ignore-scripts/);
+  // The script replaces itself mid-run; only a body behind a final call is safe.
+  assert.match(updater.trimEnd(), /\nmain "\$@"; exit \$\?$/);
+});

package/tests/npm-ignore-parity.test.mjs

@@ -0,0 +1,26 @@
+// .npmignore replaces .gitignore for npm. It must carry every .gitignore rule except
+// git-sha.json — the pack-time commit stamp that is untracked in git and exists to be
+// shipped — or the package either loses the stamp or starts shipping what git ignores.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const rules = (file) => new Set(fs.readFileSync(path.join(ROOT, file), 'utf8')
+  .split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#')));
+
+test('.npmignore is .gitignore without the commit stamp', () => {
+  const git = rules('.gitignore');
+  const npm = rules('.npmignore');
+  assert.ok(git.has('git-sha.json'), 'the stamp stays out of git');
+  assert.ok(!npm.has('git-sha.json'), 'and stays IN the package');
+  const expected = [...git].filter((r) => r !== 'git-sha.json').sort();
+  assert.deepEqual([...npm].sort(), expected);
+});
+
+test('the installer records the stamped commit when it runs from a package with no .git', () => {
+  const installer = fs.readFileSync(path.join(ROOT, 'scripts', 'install-rdc-skills.js'), 'utf8');
+  assert.match(installer, /git-sha\.json/);
+});