@zerwiz/ymir 0.1.27 → 0.1.28

package/.agents/skills/groa-update/SKILL.md

@@ -91,6 +91,36 @@ This touches only the Brokk repo and its own worktrees, never anything under `pr
    that is drift the update should have carried out — name it to the Allfather.
    Owning asset: `.agents/skills/galdr-ymirsystem/assets/installation.md`.
 
+## Updating Ymir on npm — the other half of renewing
+
+Gróa fast-forwards the **tree**; the published **packages** need the same care, and
+the traps here are quiet ones. In order:
+
+```
+npm_renewal[6]{step,how,why}:
+  "1 choose the number","fetch the registry's latest FIRST (curl …/@zerwiz%2fymir, not memory) and bump one above it","the registry can be AHEAD of main when a publish went out from a branch — main said 0.1.18 while npm served 0.1.25"
+  "2 land the bump by PR","branch → commit → gh pr create → merge; never push main (branch-guard refuses)","the delivery gate: a change leaves by PR, and the Allfather's approval is the merge"
+  "3 publish","bin/npm-publish.sh — it opens the vault's door for the token","the token is in hodd/secrets/platform.env.age, never in ~/.npmrc (that one has been stale before)"
+  "4 if it says the token is absent","the DOOR is broken, not the key: with `age` present, age -d -i hodd/secrets/age.key hodd/secrets/platform.env.age | sed -n 's/^NPM_TOKEN=//p'","bin/hodd.sh emit currently returns empty for both spellings; the vault is fine, the emit path is not — mend it"
+  "5 verify","fetch the VERSION document (…/@zerwiz/ymir/<version>) — it answers before the packument does","the registry lags for minutes; the packument can 404 while the version and tarball already resolve"
+  "6 the four apps ride along","their pins move in the same release (hlidskjalf · odrerir · sessrumnir · smidja-factory)","the distro depends on them; a pin left behind keeps shipping the old app to every user"
+```
+
+**The traps, named — each one cost a night:**
+
+- **A stale `latest` makes an install a silent no-op.** npm resolved a cached
+  `latest`, saw the same version, printed *"changed 200 packages"* and left the old
+  build in place. Publish and reinstall with **`@latest --prefer-online`**, and give
+  a stuck machine **`npm cache clean --force`**. The CLI now *says* when it is out
+  of date (once a day), so a stale install cannot hide.
+- **npm gates install scripts.** Electron's postinstall never runs, so a fresh
+  install has web surfaces and no windows; each shell needs `npm rebuild electron`
+  (the installer's `step_desktop` does it, and `bin/electron-lib.sh` verifies).
+- **A package that ships less than it needs is a fault in its own repo.** Declare
+  `name`, `files` and the absence of `private` where the package lives — never
+  rewrite a manifest at publish time (that is how `vite.config.ts` went missing and
+  every panel died on `Unexpected token '<'`).
+
 ## Safety
 
 - **Fast-forward only.** Dirty, diverged, offline, or non-default-branch targets are skipped and reported, never forced or stashed. Nothing with unlanded work is ever discarded.

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+> **Frozen 2026-09-18.** This file is the historical record and is no longer
+> written to (Rule 06: a record is never rewritten). New work is recorded as fix
+> notes — one file per fix, per component — under `docs/fixes/`, written with
+> `bin/fixes.sh record` and guarded by `bin/fixes-guard.sh`.
+
+## 2026-09-18 — the README leads with the doors that work
+
+- **The npm page and GitHub both render `README.md`**, so a user meets it first — and
+  it buried the door that always works (`npx @zerwiz/ymir`) and the PATH cure inside
+  a later section. It now opens with the one-liner (install into a prefix you own, PATH
+  written, setup run, door proven), names `npx` second, and answers *"ymir: command not
+  found"* and the stale-install trap where they happen.
+- The three doors and their honest reasons: `npx` needs no PATH at all; the one-liner
+  sets it once; `npm install -g` works wherever npm's global bin is on PATH.
+
+## 2026-09-17 — Gróa knows the npm half: how to renew the published packages
+
+- **Her skill gains the whole procedure** — choose the number from the registry (never from memory: it can be ahead of main), land the bump by PR, publish through the vault, verify by the *version document* (the packument lags), and move the four apps pins in the same release.
+- **And the traps, each of which cost a night:** a stale cached `latest` makes `npm i -g` a silent no-op that still prints success; npm gates Electron s postinstall so windows need `npm rebuild electron`; and a package must declare its own `name`/`files`/privacy where it lives rather than having a manifest rewritten at publish time.
+- The token lives in the encrypted vault; when a tool reports it absent, the DOOR is broken, not the key — and `age -d -i hodd/secrets/age.key hodd/secrets/platform.env.age` opens it while `bin/hodd.sh emit` does not.
+
+## 2026-09-17 — a stale install cannot hide, and the one-liner cannot be stranded
+
+- **The fault the Allfather hit:** `npm install -g @zerwiz/ymir` reported *"changed 200 packages"* and changed nothing — npm resolved a **cached `latest`**, saw the same version, and left the old build in place. The installed copy stayed 0.1.14 while the registry served 0.1.26, and nothing told the user. With 750+ downloads, that is not a detail.
+- **The CLI now says when it is out of date** — once a day, on a terminal, silenced by the same `ymir config notice version off` as every other notice: *"a newer Ymir is on npm 0.1.14 → 0.1.26 · update: npm i -g @zerwiz/ymir"*.
+- **The one-liner is cache-proof**: it installs `@latest` with `--prefer-online`, so a stale packument cannot strand a fresh machine.
+
 
 ## 2026-09-17 — the installer actually installs (the whole platform, then proves it)
 

package/README.md

@@ -637,15 +637,54 @@ resolved from `$YMIR_HOME/secrets/platform.env` at runtime.
 
 ---
 
-## Install — the four doors
+## Install
+
+**One command. It installs into a prefix you own, writes the PATH into your shell,
+runs the first setup, and then proves it.**
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/zerwiz/ymir/main/install.sh | bash
-npx @zerwiz/ymir install          # no global install
-git clone https://github.com/zerwiz/ymir.git ~/Ymir && cd ~/Ymir && bin/ymir-install.sh
-npm install -g @zerwiz/ymir       # the CLI, global
 ```
 
+**No PATH, no prefix, nothing to configure — run it without installing:**
+
+```bash
+npx @zerwiz/ymir
+```
+
+**Already manage Node and npm yourself:**
+
+```bash
+npm install -g @zerwiz/ymir      # then: ymir
+```
+
+### If `ymir` is "command not found"
+
+The command **is** installed — npm put it in its global bin directory, and your
+shell does not look there. This is npm's behaviour, not Ymir's, and it is the most
+common *"it does not work"* in the whole Node ecosystem.
+
+```bash
+npm prefix -g                                  # where npm puts global commands
+ls "$(npm prefix -g)/bin/ymir"                 # the command is there
+export PATH="$(npm prefix -g)/bin:$PATH"       # this shell
+echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc   # every shell after
+```
+
+**Or skip the question entirely** — `npx @zerwiz/ymir` works with no PATH at all,
+and the one-liner above sets it once.
+
+### If the version never changes
+
+An install can *succeed* and change nothing: npm may resolve a cached `latest` and
+report success while the old build stays. Clear it once:
+
+```bash
+npm cache clean --force && npm i -g @zerwiz/ymir@latest --prefer-online
+```
+
+The CLI itself now says when it is out of date, once a day.
+
 **Who can install this today.** The Ymir distro is private while it is young —
 so `curl`, `npx` and `git clone` work for the author and invited users, not for
 the public (an unknown clone returns 404). If you would like access, ask:
@@ -736,11 +775,11 @@ alone if you want only that hall.
 
 ```
 packages[5]{package,what,live}:
-  "@zerwiz/ymir","the distro — the runtime, the doors, the installer, the plan","0.1.12"
-  "@zerwiz/hlidskjalf","the high seat — the control plane, the gate and the landing","0.1.0"
-  "@zerwiz/odrerir","the live hall — the board on :4322","0.1.0"
+  "@zerwiz/ymir","the distro — the runtime, the doors, the installer, the plan","0.1.28"
+  "@zerwiz/hlidskjalf","the high seat — the control plane, the gate and the landing","0.1.1"
+  "@zerwiz/odrerir","the live hall — the board on :4322","0.1.1"
   "@zerwiz/smidja-factory","the smithy — the agent factory, its skills and the visualizer on :8437","0.1.1"
-  "@zerwiz/sessrumnir","the seat-hall — the desktop where you speak with Brokk","0.1.9"
+  "@zerwiz/sessrumnir","the seat-hall — the desktop where you speak with Brokk","0.1.10"
 ```
 
 ```bash

package/bin/fixes-guard.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# fixes-guard.sh — the delivery gate reads, and it checks the RECORD.
+#
+# What it replaces, and why: `changelog-guard` passed if a push range merely
+# *touched* CHANGELOG.md — a stray line satisfied it, so it never verified that
+# anything was recorded. And the hook in front of it FOLDED fragments into the
+# monolith, mutating the tree mid-push and then demanding a commit for the edit it
+# had just made.
+#
+# This gate only READS. A push must carry at least one new fix note
+# (`docs/fixes/<component>/<version>-<slug>.md`), and it says which of the push's
+# touched paths that note's component covers — a mismatch is reported, never
+# silently accepted.
+#
+#   fixes-guard.sh --install     # seat it as the pre-push hook (replacing the old one)
+#   fixes-guard.sh --check       # judge the current branch against its base, by hand
+#   git push                     # the hook runs it with the refs on stdin
+#
+# Override, loudly: YMIR_SKIP_FIXES_GUARD=1
+#
+# Exit: 0 the record is there, 1 it is not, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+cd "$ROOT" || exit 1
+
+[ "${YMIR_SKIP_FIXES_GUARD:-0}" = 1 ] && { printf 'fixes-guard[1]{gate,result}:\n  "push","skipped (YMIR_SKIP_FIXES_GUARD=1)"\n'; exit 0; }
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help) sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  --install)
+    H="$(git rev-parse --git-path hooks)/pre-push"
+    mkdir -p "$(dirname "$H")"
+    cat >"$H" <<EOF
+#!/usr/bin/env bash
+# pre-push — the delivery gate. Installed by bin/fixes-guard.sh --install.
+#   1. branch-guard — never push a protected branch
+#   2. fixes-guard  — every push carries a fix note for what it changed (read-only)
+set -u
+refs="\$(mktemp)"; trap 'rm -f "\$refs"' EXIT
+cat >"\$refs"
+"$ROOT/bin/branch-guard.sh" <"\$refs" || exit 1
+"$ROOT/bin/fixes-guard.sh" <"\$refs" || exit 1
+EOF
+    chmod +x "$H"
+    printf 'fixes-guard[1]{gate,result}:\n  "hook","installed at %s"\n' "${H#"$ROOT"/}"
+    exit 0 ;;
+  --check) ;;
+  "") ;;
+  *) printf 'error: unknown flag %s\nhelp: bin/fixes-guard.sh [--install|--check]\n' "$1" >&2; exit 2 ;;
+esac
+
+# ── the judgement ────────────────────────────────────────────────────────────
+# The range: from stdin when a hook calls us, else the branch against its base.
+refs="$(cat 2>/dev/null || true)"
+head_sha=""; remote_sha=""
+if [ -n "$refs" ]; then
+  while read -r _local local_sha _remote remote_sha2; do
+    [ -n "${local_sha:-}" ] || continue
+    case "$local_sha" in 000000*) continue ;; esac
+    head_sha="$local_sha"; remote_sha="${remote_sha2:-}"
+  done <<<"$refs"
+fi
+[ -n "$head_sha" ] || head_sha="$(git rev-parse HEAD)"
+
+base=""
+if [ -n "$remote_sha" ] && [ "$remote_sha" != 0000000000000000000000000000000000000000 ]; then
+  base="$remote_sha"
+else
+  for cand in origin/main main master; do
+    git rev-parse --verify -q "$cand" >/dev/null 2>&1 || continue
+    base="$(git merge-base "$head_sha" "$cand" 2>/dev/null || true)"
+    [ -n "$base" ] && break
+  done
+fi
+[ -n "$base" ] || { printf 'fixes-guard[1]{gate,result}:\n  "push","no base to compare — first push of a branch is judged on its own"\n'; exit 0; }
+
+range="${base}..${head_sha}"
+notes="$(git diff --name-only --diff-filter=A "$range" 2>/dev/null | grep -E '^docs/fixes/[a-z]+/[0-9][^/]*\.md$' || true)"
+touched="$(git diff --name-only "$range" 2>/dev/null | grep -v '^docs/fixes/' | grep -v '^CHANGELOG' || true)"
+
+if [ -z "$notes" ]; then
+  printf 'fixes-guard[1]{gate,result}:\n  "push","refused — no fix note in this range"\n' >&2
+  printf 'help: bin/fixes.sh record --component=<%s> --version=<v> --title="what changed"\n' \
+    "install|runtime|skills|agents|hlidskjalf|odrerir|sessrumnir|smidja|hoard|gate" >&2
+  printf 'note: a note is a file under docs/fixes/<component>/ — write one, commit it, push again.\n' >&2
+  exit 1
+fi
+
+# The record is there: now say whether it speaks to what the push changed.
+covered=0
+for n in $notes; do
+  c="$(printf '%s' "${n#docs/fixes/}" | cut -d/ -f1)"
+  case "$touched" in
+    *"$c"*) covered=$((covered+1)) ;;
+    *bin/fixes*|*install*) [ "$c" = install ] && covered=$((covered+1)) ;;
+    *bin/ymir*|*bin/sessrumnir*|*bin/smidja*|*bin/npm-publish*|*.agents/skills/*) covered=$((covered+1)) ;;
+  esac
+done
+
+count="$(printf '%s\n' "$notes" | grep -c . || true)"
+if [ "$covered" -gt 0 ]; then
+  printf 'fixes-guard[1]{gate,result}:\n  "push","ok — %s note(s), and the record speaks to the change"\n' "$count"
+else
+  printf 'fixes-guard[1]{gate,result}:\n  "push","ok — %s note(s); none names a path this range touched"\n' "$count"
+  printf 'note: a note for another component is still a record — but say what THIS push changed.\n' >&2
+  printf '      components touched: %s\n' "$(printf '%s' "$touched" | head -4 | tr '\n' ' ')" >&2
+fi
+exit 0

package/bin/fixes.sh

@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# fixes.sh — the fix notes. ONE FILE PER FIX, and nothing to fold.
+#
+# The two systems this replaces both failed us, and for the same reason: they kept
+# a MONOLITH (CHANGELOG.md) and fed it from fragments (CHANGELOG.d). The pre-push
+# hook folded the fragments into the monolith, then demanded a commit for the edit
+# it had just made — a push that mutates the tree it is pushing, and a gate that
+# passed if a range merely *touched* the file.
+#
+# So there is no monolith and no fold here. A note IS a file:
+#
+#   docs/fixes/<component>/<version>-<slug>.md
+#
+# Two branches never write the same path, so the collision is impossible. The
+# history of a component is its directory, sorted. Nothing is ever assembled at
+# push time, and the gate that guards it only READS (bin/fixes-guard.sh).
+#
+#   bin/fixes.sh record --component=install --version=0.1.28 --title="…" \
+#                       [--why="…"] [--files="a,b"] [--date=YYYY-MM-DD]
+#   bin/fixes.sh list [<component>]          # the components, or one's notes
+#   bin/fixes.sh show <file|component>       # a note, or the newest of a component
+#   bin/fixes.sh diff --component=X --from=V --to=V
+#   bin/fixes.sh validate                    # every note's header, and its order
+#   bin/fixes.sh components                  # just the names
+#
+# Exit: 0 ok, 1 error, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+FIXES="$ROOT/docs/fixes"
+
+# The components are the machine's own parts, not an invented list.
+COMPONENTS="install runtime skills agents hlidskjalf odrerir sessrumnir smidja hoard gate"
+
+usage() { sed -n '2,26p' "$0" | sed 's/^# \{0,1\}//'; }
+die() { printf 'error: %s\n' "$1" >&2; [ -n "${2:-}" ] && printf 'help: %s\n' "$2" >&2; exit 1; }
+known() { case " $COMPONENTS " in *" $1 "*) return 0 ;; *) return 1 ;; esac; }
+slugify() { printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -c 'a-z0-9' '-' | sed 's/--*/-/g; s/^-//; s/-$//' | cut -c1-56; }
+
+action="${1-}"; shift || true
+case "$action" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+component=""; version=""; title=""; why=""; files=""; date=""; from=""; to=""
+for a in "$@"; do
+  case "$a" in
+    --component=*) component="${a#*=}" ;;
+    --version=*)   version="${a#*=}" ;;
+    --title=*)     title="${a#*=}" ;;
+    --why=*)       why="${a#*=}" ;;
+    --files=*)     files="${a#*=}" ;;
+    --date=*)      date="${a#*=}" ;;
+    --from=*)      from="${a#*=}" ;;
+    --to=*)        to="${a#*=}" ;;
+    -*) die "unknown argument $a" "bin/fixes.sh --help" ;;
+    *) pos="${a}" ;;
+  esac
+done
+
+notes_of() {  # <component> — its notes, newest first (the version decides the order)
+  local c="$1"
+  [ -d "$FIXES/$c" ] || return 0
+  ls -1 "$FIXES/$c"/*.md 2>/dev/null | sort -V -r
+}
+
+case "$action" in
+  components)
+    printf 'components[%d]{name}:\n' "$(printf '%s\n' $COMPONENTS | wc -l | tr -d ' ')"
+    for c in $COMPONENTS; do printf '  "%s"\n' "$c"; done
+    ;;
+
+  list)
+    c="${pos:-${component:-}}"
+    if [ -n "$c" ]; then
+      known "$c" || die "unknown component $c" "one of: $COMPONENTS"
+      n=0; while IFS= read -r f; do [ -n "$f" ] || continue; n=$((n+1)); printf '  "%s","%s","%s"\n' "$c" "$(basename "$f")" "$(sed -n '1s/^## [^·]*· \([^ ]*\) ·.*/\1/p' "$f")"; done < <(notes_of "$c")
+      [ "$n" -gt 0 ] || printf 'fixes: %s has no notes yet\n' "$c"
+    else
+      printf 'fixes[%d]{component,notes}:\n' "$(printf '%s\n' $COMPONENTS | wc -l | tr -d ' ')"
+      for c in $COMPONENTS; do
+        cnt=$(notes_of "$c" | grep -c . || true)
+        printf '  "%s",%s\n' "$c" "$cnt"
+      done
+    fi
+    ;;
+
+  show)
+    what="${pos:-${component:-}}"; [ -n "$what" ] || die "what shall I show?" "bin/fixes.sh show <component|file>"
+    if [ -f "$what" ]; then f="$what"
+    elif [ -f "$FIXES/$what" ]; then f="$FIXES/$what"
+    else
+      known "$what" || die "unknown component $what" "one of: $COMPONENTS"
+      f="$(notes_of "$what" | head -1)"
+      [ -n "$f" ] || { printf 'fixes: %s has no notes yet\n' "$what"; exit 0; }
+    fi
+    cat "$f"
+    ;;
+
+  record)
+    [ -n "$component" ] && [ -n "$version" ] && [ -n "$title" ] \
+      || die "record needs --component, --version and --title" \
+             "bin/fixes.sh record --component=install --version=0.1.28 --title=\"…\""
+    known "$component" || die "unknown component $component" "one of: $COMPONENTS"
+    date="${date:-$(date -u +%Y-%m-%d)}"
+    dir="$FIXES/$component"; mkdir -p "$dir"
+    f="$dir/${version}-$(slugify "$title").md"
+    [ -e "$f" ] && die "that note already exists: ${f#"$ROOT"/}" "bin/fixes.sh show ${f#"$ROOT"/}"
+    {
+      printf '## %s · %s · %s — %s\n\n' "$component" "$version" "$date" "$title"
+      [ -n "$why" ] && printf '### Why\n%s\n\n' "$why"
+      printf '### Files\n'
+      if [ -n "$files" ]; then printf '%s' "$files" | tr ',' '\n' | sed 's/^ *//; s/^/- `/; s/$/`/'
+      else printf -- '- *(none named)*\n'; fi
+    } >"$f"
+    printf 'fixes[1]{component,version,note}:\n  "%s","%s","%s"\n' "$component" "$version" "${f#"$ROOT"/}"
+    ;;
+
+  diff)
+    [ -n "$component" ] || die "diff needs --component" "bin/fixes.sh diff --component=install --from=0.1.27 --to=0.1.28"
+    known "$component" || die "unknown component $component"
+    n=0
+    while IFS= read -r f; do
+      [ -n "$f" ] || continue
+      b="$(basename "$f")"
+      case "$b" in
+        "${from}"-*|"${to}"-*) n=$((n+1)); printf '\n'; cat "$f" ;;
+      esac
+    done < <(notes_of "$component")
+    [ "$n" -gt 0 ] || printf 'fixes: nothing between %s and %s for %s\n' "$from" "$to" "$component"
+    ;;
+
+  validate)
+    fails=0; checked=0
+    [ -d "$FIXES" ] || { printf 'fixes: docs/fixes/ does not exist yet\n'; exit 0; }
+    for d in "$FIXES"/*/; do
+      [ -d "$d" ] || continue
+      c="$(basename "$d")"
+      known "$c" || { printf '  "%s","unknown component directory"\n' "$c"; fails=$((fails+1)); continue; }
+      for f in "$d"*.md; do
+        [ -e "$f" ] || continue
+        checked=$((checked+1))
+        hdr="$(sed -n '1p' "$f")"
+        printf '%s' "$hdr" | grep -qE "^## ${c} · ([0-9]+\.[0-9]+\.[0-9]+[^ ]*|unversioned) · [0-9]{4}-[0-9]{2}-[0-9]{2} — .+" \
+          || { printf '  "%s","malformed header: %s"\n' "${f#"$ROOT"/}" "$hdr"; fails=$((fails+1)); }
+        grep -q '^### Files$' "$f" || { printf '  "%s","no Files section"\n' "${f#"$ROOT"/}"; fails=$((fails+1)); }
+      done
+    done
+    if [ "$fails" = 0 ]; then printf 'fixes[1]{state,checked}:\n  "valid",%s\n' "$checked"
+    else printf 'fixes[1]{state,failed}:\n  "invalid",%s\n' "$fails"; exit 1; fi
+    ;;
+
+  *) die "unknown action ${action:-}" "bin/fixes.sh [record|list|show|diff|validate|components]" ;;
+esac

package/bin/ymir.js

@@ -82,6 +82,40 @@ function versionNotice() {
   } catch { /* a version notice must never break a door */ }
 }
 
+// ── is this copy current? ────────────────────────────────────────────────────
+// An install can succeed and change NOTHING: npm resolves a cached `latest`, sees
+// the same version, and says "changed 200 packages" while the old build stays. A
+// user cannot tell — so the tool says it, once a day, where a human is watching.
+function checkForUpdate() {
+  if (!process.stderr.isTTY || process.env.YMIR_NO_UPDATE_CHECK === '1') return;
+  if (noticeState('version') === 'off') return;
+  try {
+    const os = require('node:os');
+    const stamp = path.join(STATE_DIR, 'update-check');
+    const today = new Date().toISOString().slice(0, 10);
+    if (fs.existsSync(stamp) && fs.readFileSync(stamp, 'utf8').trim() === today) return;
+    fs.mkdirSync(STATE_DIR, { recursive: true });
+    fs.writeFileSync(stamp, today + '\n');
+    const https = require('node:https');
+    const req = https.get('https://registry.npmjs.org/@zerwiz/ymir/latest', { timeout: 1500 }, (res) => {
+      let body = '';
+      res.on('data', (d) => { body += d; });
+      res.on('end', () => {
+        try {
+          const latest = JSON.parse(body).version;
+          if (latest && latest !== pkg.version) {
+            process.stderr.write('\n' + bronze('  a newer Ymir is on npm  ') + faint(`${pkg.version} → `) + bronze(latest) + '\n' +
+              faint('  update:  npm i -g @zerwiz/ymir    (no PATH? npx @zerwiz/ymir)') + '\n' +
+              (noticeState('hints') === 'off' ? '' : faint('      (not again: ymir config notice version off)') + '\n'));
+          }
+        } catch { /* a notice must never break a door */ }
+      });
+    });
+    req.on('error', () => {});
+    req.on('timeout', () => req.destroy());
+  } catch { /* never break a door */ }
+}
+
 // ── the doors ────────────────────────────────────────────────────────────────
 // verb → { script, args } — args are prepended to whatever the operator passes,
 // so a verb can be a doorway to a sub-verb of a script that has several.
@@ -143,6 +177,7 @@ const argv = process.argv.slice(2);
 const first = argv[0];
 
 versionNotice();
+checkForUpdate();
 if (!first) run(DOORS.install.script, []);
 if (first === '--version' || first === '-v' || first === '-V') {
   process.stdout.write(`${pkg.version}\n`);

package/docs/fixes/agents/unversioned-2026-09-11-chat-uses-the-root-pi-model-catalog.md

@@ -0,0 +1,15 @@
+## agents · unversioned · 2026-09-11 — Chat uses the root Pi model catalog
+
+### Why
+- **Fix:** the Kaia chat guessed a llama.cpp model id by regex and fell through
+  to the Bifrost bridge (`:4603` → 401) when the guess failed.
+- **Now:** the gate API reads the operator's root Pi catalog
+  (`~/.pi/agent/models.json`) for the exact provider → base URL, model id, and
+  key (llama.cpp router `:8080`, `sk-not-key-required`). A chosen local model
+  is tried only on its own base; the default is the operator's Pi default
+  (`qwen3.6-35b-a3b@iq3_s`). `/api/chat/models` lists the real connected set.
+- **Verified:** `gemma-4-12b@q3_k_s`, `qwen3.6-35b-a3b@iq3_s` (default), and
+  `qwen3.5-9b@q4_k_s` all answered live; no 401.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-11-shared-well-for-every-harness-no-mock-clickable-memories.md

@@ -0,0 +1,26 @@
+## agents · unversioned · 2026-09-11 — Shared well for every harness; no mock; clickable memories
+
+### Why
+- **Harnesses:** the engram MCP server is now registered for all four OpenCode
+  accounts (`opencode`, `opencode-rd`, `opencode-work`, `opencode-oczer`), Pi
+  (`~/.pi/agent/settings.json` + `mcp.json` + `.pi/mcp.json`), Claude, Cursor,
+  and Codex. Registered **unscoped** so every harness reads the one shared well
+  (per-call `agent_id` still attributes writes).
+- **No mock:** purged every test/mock episode (`smoke`/`Test observation`) from
+  both the engram store and `episodes.jsonl` → 367 true episodes. Test writes
+  never enter the well.
+- **UI:** Well memories are now **clickable** — `GET /api/well/episode?id=` and
+  a bridge `/episode` endpoint feed a modal with the full memory text.
+- **Bridge fix:** `/recent` and `/recall` restored; added `/episode`.
+- **Lifecycle fix:** `bifrost-bridge.sh` / `mimir-bridge.sh` now stop by process
+  match when the PID file is missing, and record the PID when the port is
+  already up — so `scripts/stop.sh` truly lowers the whole system and
+  `scripts/start.sh` truly raises it.
+- **Galdr:** new asset `.agents/skills/galdr-ymirsystem/assets/memory-well.md` (store,
+  bridge, MCP, harness matrix, laws, verify), routed in `SKILL.md`; registry +
+  harness README updated; mirrored to tyr.
+- **Verified:** MCP recall 1.0 / stats 367, full stop→start cycle (3888/3889/
+  4602/4603/8437), compliance 8/8, smoke 8/8.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-13-gleipnir-sees-when-an-agent-is-turned-off.md

@@ -0,0 +1,26 @@
+## agents · unversioned · 2026-09-13 — Gleipnir sees when an agent is turned off
+
+### Why
+- **Problem:** the machine lock stuck “held by another Brokk session” forever.
+  Nothing released it ( `gleipnir_lock_release` had zero callers; Pi's exit
+  hook only stopped the arm child), and liveness was `kill(0)` alone — which
+  reports a zombie (dead but unreaped) and a recycled pid as alive, so an
+  agent you turned off kept the helm until its pid happened to look gone.
+  Worse, the Sessrúmnir desktop RPC session holds the live lock yet never
+  arms supervision (no turn ever calls `gna_watch_arm`), stranding every
+  other session read-only.
+- **Fix:** `bin/gleipnir-lock-lib.sh` now records the owner's starttime in a
+  `brokk.lock.starttime` sidecar and reaps a holder whose `/proc/<pid>/stat`
+  state is `Z`/`X` or whose starttime no longer matches (pid reuse) — dead,
+  zombie, and recycled holders are cleared at session start/acquire. Gná
+  (`gna-pi-watch.ts`) mirrors that liveness, reclaims a stale lock directly in
+  `gna_watch_arm` (`missing` no longer punts to saga-session-start.sh), and
+  drops its own lock on real process exit (`releaseLockIfOwned`); the turn-end
+  guard (`syn-turnend-guard.ts`) uses the same zombie-aware check.
+- **Impact:** turning an agent off — cleanly, by kill (zombie), or after pid
+  reuse — frees the machine lock for the next session. The live desktop seat
+  still holds it until that app is closed or its own session arms; that is the
+  law (on
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-14-the-eindri-brokk-wake-bridge-they-can-talk-back-now.md

@@ -0,0 +1,23 @@
+## agents · unversioned · 2026-09-14 — The Eindri→Brokk wake bridge (they can talk back now)
+
+### Why
+- **Ask:** the seated smiths' reports lived in their panes only; the Allfather
+  wanted a feature that wakes Brokk when an Eindri reports, so the fleet's
+  doings reach the primary's session — "we are in control, Brokk".
+- **Built:** `bin/eindri-seen.sh` (condition — a report file landed or herdr
+  shows the smith left `working`), `bin/eindri-acclaim.sh` (action — files the
+  report durably under state/eindri-reports/, marks done under
+  state/eindri-done/, appends the wake to state/.wake-queue for Sága's drain,
+  sounds the desktop note), and `bin/eindri-watch.sh` (the control door —
+  `arm | retire | list | reconcile`, one when-source per smith on the Norns'
+  loom via fm-procevent-when.sh, action hash-bound, fires once on a stable
+  true, terminal, re-armable).
+- **Armed live:** when-odrerir (already fired — his report was filed) and
+  when-sessrumnir-cloth (still working). `fm-procement.sh reconcile` started=2.
+- **First report delivered through the wire:** odrerir's Óðrerir saga — deck
+  green at :4322, 52 Chromium checks, commit 38a326b on yggdrasil/odrerir, main
+  untouched, plus the hall.ymir.zerwiz.org server story (setup-hall.sh) and
+  three asks awaiting the Allfather (go live, landing mobile wart, PLAN log).
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-16-a-sandboxed-worker-cannot-think-auto-stops-killing-agent.md

@@ -0,0 +1,18 @@
+## agents · unversioned · 2026-09-16 — a sandboxed worker cannot think: `auto` stops killing agents
+
+### Why
+Spawning an Eindri with the default `--isolation auto` produced an **empty pane
+and no status line**. The cause: `auto` chose Utgard whenever the image existed,
+and Utgard runs with `--network none` — so the worker could reach neither its
+cloud model (OpenCode Go) nor a local one (llama.cpp) and died at launch, silently.
+
+- **`auto` now keeps the worker in its worktree.** A spawned Eindri is a
+  model-driven worker: it must reach a model endpoint to think. Utgard is for
+  untrusted *code*, not for the agent's own brain, so the automatic choice is
+  `off`, and it says why.
+- **`--isolation on` warns loudly.** It stays available for a sandbox that can
+  actually reach a model, but it now prints that Utgard has no network and the
+  agent will die silently without one.
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-17-agents-md-states-the-one-law-no-private-data-in-the-publ.md

@@ -0,0 +1,25 @@
+## agents · unversioned · 2026-09-17 — AGENTS.md states the one law: no private data in the public repo
+
+### Why
+- **The law is now first.** A `first_law` block sits directly under the mandate
+  in `AGENTS.md`: never store personal or private data in this repo — not a
+  secret, a key, a name, a plan, a schedule, a client, a credential, or a note.
+  The repo is public; private data lives at `$YMIR_HOME`, under `hodd/`.
+- **The private-data section was rebuilt against the disk.** It had duplicated
+  `secrets/` and `identity/` lines, no `hodd/` level, and a layout that no longer
+  matched the home. It now shows the real tree, names `$YMIR_HOME/hodd/` as *the*
+  private data path, and records that `bin/hoard-lib.sh` is the one source of
+  truth for it.
+- **Every `$YMIR_HOME/...` path in the file was corrected** to `$YMIR_HOME/hodd/...`
+  — the directory rules table, the registry reference, the secrets reference, and
+  the append-only ledger path all pointed at the old flat layout.
+- **Two wards are now documented**: `bin/secret-guard.sh` (a secret entering the
+  repo) and Eir's `hoard` surface (private data drifting outside the hoard, or a
+  `.ymir-layout.yaml` naming a path that does not exist).
+- **Staging discipline is written down.** Stage named files in the home, never
+  `git add -A` — a scratch file written seconds earlier gets swept into a commit
+  and pushed. This happened this day and cost a history rewrite.
+- **`hodd/AGENTS.example.md`** carried the same stale flat paths and a wrong
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*

package/docs/fixes/agents/unversioned-2026-09-17-every-figure-loads-the-agent-directory-was-never-read.md

@@ -0,0 +1,25 @@
+## agents · unversioned · 2026-09-17 — every figure loads: the agent directory was never read
+
+### Why
+- **The bug, stated plainly.** Twenty agent profiles existed, twenty symlinks
+  pointed at them, and every gate was green — yet OpenCode loaded **three**
+  agents. The symlinks lived in `.opencode/agent/` (SINGULAR). OpenCode reads
+  `.opencode/agents/` (PLURAL). Twenty correct links sat in a directory no loader
+  opened, so only `brokk` and `hnoss` — the two declared by hand in
+  `opencode.json` — ever appeared.
+- **The directory is fixed and migrated.** `.opencode/agent/` → `.opencode/agents/`
+  (20 links, all resolving). `bin/valknut-load.sh` now writes the plural path and
+  **migrates a legacy singular dir forward**, so an old home heals instead of
+  silently keeping its agents invisible.
+- **The roster now declares what it names.** `bin/agents-config.sh apply` only
+  touched an agent already present in `opencode.json` (`if a in ablock`), so a
+  figure the roster knew but the config had never seen stayed undeclared. The
+  roster is the source of truth; a name in it now reaches the harness config.
+- **A new gate catches the class.** `compliance-check.sh` gains **`roster`**: the
+  roster (`config/agents.yaml.example`) and the canonical tree
+  (`.agents/agents/*.md`) must name the same figures. A figure in the tree but not
+  the roster falls to `default_model` and is never declared; a figure in the
+  roster with no profile is a phantom. This is the check that would have caught
+
+### Files
+- *(carried from the frozen CHANGELOG.md)*