@zerwiz/ymir 0.1.4 → 0.1.5

package/bin/saga-sessionstart-run.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+# saga-sessionstart-run.sh - session-open entry point for run-tier harnesses.
+#
+# Sága's runner. A harness whose session-open adapter can RUN a command invokes
+# this; it decides from the session-open source whether the open needs the full
+# digest, a context re-emit, or a short nudge. Ported from the upstream agent-distro reference for plan 29.
+#
+# Usage: saga-sessionstart-run.sh [--source <source>] [--pi-prerequisite]
+#   --source  startup|new|clear|compact|resume|reload|fork. When omitted it is
+#             read from a Claude/Codex-shaped JSON hook payload on stdin.
+#   --pi-prerequisite  Pi extension mode: an intentional stand-down exits 3 so
+#             provider preflight can distinguish it from an eligible attempt
+#             that settled without output.
+#
+# Every ordinary transport path exits 0: a failed session start must reach the
+# agent as digest text it can act on, never as a refusal to open the session.
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+COMPLETION_FILE="$STATE/.session-start-complete"
+
+SOURCE=""
+PI_PREREQUISITE=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --source) SOURCE=${2:-}; if [ $# -ge 2 ]; then shift 2; else shift; fi ;;
+    --pi-prerequisite) PI_PREREQUISITE=1; shift ;;
+    *) shift ;;
+  esac
+done
+
+if [ -z "$SOURCE" ] && [ ! -t 0 ]; then
+  payload=$(cat 2>/dev/null || true)
+  case "$payload" in
+    *'"source":"startup"'*|*'"source": "startup"'*) SOURCE=startup ;;
+    *'"source":"clear"'*|*'"source": "clear"'*) SOURCE=clear ;;
+    *'"source":"compact"'*|*'"source": "compact"'*) SOURCE=compact ;;
+    *'"source":"resume"'*|*'"source": "resume"'*) SOURCE=resume ;;
+    *'"source":"fork"'*|*'"source": "fork"'*) SOURCE=fork ;;
+    *'"source":"new"'*|*'"source": "new"'*) SOURCE=new ;;
+  esac
+fi
+SOURCE="${SOURCE:-startup}"
+
+# Pi prerequisite eligibility: this build always considers the primary eligible.
+# A deployment that must stand down sets BROKK_SESSIONSTART_INELIGIBLE=1.
+if [ "$PI_PREREQUISITE" = "1" ] && [ "${BROKK_SESSIONSTART_INELIGIBLE:-0}" = "1" ]; then
+  exit 3
+fi
+
+mkdir -p "$STATE"
+
+case "$SOURCE" in
+  startup|new)
+    "$SCRIPT_DIR/saga-session-start.sh"
+    : >"$COMPLETION_FILE"
+    ;;
+  clear|compact)
+    if [ -f "$COMPLETION_FILE" ]; then
+      printf 'CONTEXT RE-EMIT (source=%s)\n\n' "$SOURCE"
+      printf 'Session-start context was already taken this lock. Re-read data/operator.md,\n'
+      printf 'data/projects.md, and data/learnings.md only if this turn needs them.\n'
+    else
+      "$SCRIPT_DIR/saga-session-start.sh"
+      : >"$COMPLETION_FILE"
+    fi
+    ;;
+  resume|reload|fork)
+    printf 'Run `%s` exactly once now, before executing any other instructions.\n' "bash $SCRIPT_DIR/saga-session-start.sh"
+    ;;
+  *)
+    "$SCRIPT_DIR/saga-session-start.sh"
+    : >"$COMPLETION_FILE"
+    ;;
+esac
+
+exit 0

package/bin/saga-wake-drain.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# saga-wake-drain.sh - present durable Brokk wakes.
+#
+# Sága sees the queue. This drains the durable wake queue written by the watcher
+# and prints each record; records stay durable until acknowledged. Ported/trimmed
+# from the upstream wake-drain contract for plan 29.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="${BROKK_ROOT_OVERRIDE:-$(cd "$SCRIPT_DIR/.." && pwd)}"
+BROKK_HOME="${BROKK_HOME:-$ROOT}"
+STATE="${BROKK_STATE_OVERRIDE:-$BROKK_HOME/state}"
+
+mkdir -p "$STATE"
+QUEUE="$STATE/.wake-queue"
+# The FM runner's own durable queue (its published check-wakes) lives under the
+# .agents home, not the main state. The watcher hollers on BOTH doors; a drain
+# that reads only one lets strikes hide in the other. Combine them here.
+FMQ="$SCRIPT_DIR/../.agents/state/.wake-queue"
+if [ -s "$FMQ" ]; then
+  printf 'FM wake queue: %s pending (fm-queued wakes below)\n' "$(wc -l <"$FMQ" | tr -d '[:space:]')"
+  while IFS= read -r line; do
+    [ -n "$line" ] && printf 'WAKE %s\n' "$line"
+  done <"$FMQ"
+  printf 'FM_ACK_REQUIRED: acknowledge handled fm wakes to drop them from the fm queue\n'
+fi
+
+if [ ! -s "$QUEUE" ]; then
+  printf 'wake queue: 0 pending\n'
+else
+  count=$(wc -l <"$QUEUE" | tr -d '[:space:]')
+  printf 'wake queue: %s pending\n' "${count:-0}"
+  while IFS= read -r line; do
+    [ -n "$line" ] && printf 'WAKE %s\n' "$line"
+  done <"$QUEUE"
+  printf 'WAKE_ACK_REQUIRED: acknowledge handled wakes to drop them from the queue\n'
+fi
+
+# Open-decision markers (approval gates) left unhandled.
+decisions=$(find "$STATE" -maxdepth 1 -name '*.decision' 2>/dev/null | wc -l | tr -d '[:space:]')
+printf 'open decisions: %s\n' "${decisions:-0}"

package/bin/secret-guard.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# secret-guard.sh — refuse to commit obvious secrets or private env files.
+#
+#   bin/secret-guard.sh            # scan the staged change (used as pre-commit)
+#   bin/secret-guard.sh --install  # wire it into .git/hooks/pre-commit
+#   bin/secret-guard.sh --all      # scan every tracked file once
+#
+# Exit 1 on any hit, so a commit is blocked before a secret leaves the machine.
+set -u
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PATTERNS='(AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|(ghp|gho|ghs|ghr)_[A-Za-z0-9]{36}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]+|AIza[0-9A-Za-z_-]{35}|(CLOUDFLARE_API_TOKEN|OPENCODE_GO_API_KEY|GITHUB_TOKEN|OPENAI_API_KEY|ANTHROPIC_API_KEY)[[:space:]]*=[[:space:]]*[A-Za-z0-9_./+=-]{8,})'
+
+# Paths deliberately exempt (test fixtures with fake secret-shaped strings),
+# one glob per line in .secret-guardignore.
+IGNORE="$ROOT/.secret-guardignore"
+is_ignored() {
+  [ -r "$IGNORE" ] || return 1
+  local p
+  while IFS= read -r p; do
+    [ -n "$p" ] || continue
+    case "$p" in \#*) continue ;; esac
+    case "$1" in $p) return 0 ;; esac
+  done <"$IGNORE"
+  return 1
+}
+
+case "${1:-}" in
+  -v|-V|--version) printf '1.0.0\n'; exit 0 ;;
+  -h|--help) sed -n '2,9p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+  --install)
+    hook="$ROOT/.git/hooks/pre-commit"
+    mkdir -p "$(dirname "$hook")" || exit 1
+    printf '#!/usr/bin/env bash\n"%s/public-guard.sh" "$@" || exit 1\n"%s/docs-guard.sh" "$@" || exit 1\n"%s/private-guard.sh" "$@" || exit 1\nexec "%s/secret-guard.sh" "$@"\n' "$SCRIPT_DIR" "$SCRIPT_DIR" "$SCRIPT_DIR" "$SCRIPT_DIR" >"$hook"
+    chmod +x "$hook"
+    printf 'secret-guard[1]{action,path}:\n  "install","%s"\n' "$hook"
+    exit 0 ;;
+esac
+
+scan_list() {
+  local hit=0 f
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    is_ignored "$f" && continue
+    case "$f" in
+      .env.local|*/.env.local|*.env.local|.env.realm|*/.env.realm)
+        printf 'secret-guard: private env file: %s\n' "$f" >&2; hit=1; continue ;;
+    esac
+    if git -C "$ROOT" show ":$f" 2>/dev/null | sed 's/AKIAIOSFODNN7EXAMPLE//g' | grep -Eq "$PATTERNS"; then
+      printf 'secret-guard: possible secret in %s\n' "$f" >&2; hit=1
+    fi
+  done
+  return "$hit"
+}
+
+if [ "${1:-}" = "--all" ]; then
+  scan_list < <(git -C "$ROOT" ls-files)
+else
+  scan_list < <(git -C "$ROOT" diff --cached --name-only --diff-filter=ACM)
+fi || { printf 'secret-guard: blocked — remove the secret or move it to a .example file\n' >&2; exit 1; }
+exit 0

package/bin/sessrumnir-ensure.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# sessrumnir-ensure.sh — ensure the Sessrúmnir desktop GUI is present and runnable.
+#
+# **Sessrúmnir** is the seat-hall where the Allfather converses with the
+# machine: a vendored, re-themed fork of the Apache-2.0 **pi-desktop** project
+# (github.com/FaqFirebase/pi-desktop, v0.1.7-alpha) living at apps/sessrumnir.
+# The external engine keeps its product name; the GUI the user sees is
+# Sessrúmnir. Dependencies are never committed — this script installs them on
+# first run, exactly as scripts/electron.sh does for the other desktop apps.
+#
+# Usage:
+#   sessrumnir-ensure.sh status
+#   sessrumnir-ensure.sh ensure [--install]
+#   sessrumnir-ensure.sh install
+#   sessrumnir-ensure.sh --version
+#
+# Exit: 0 ready (or made ready), 1 not ready, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+APP="$ROOT/apps/sessrumnir"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,16p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+CMD="${1-}"; shift || true
+DO_INSTALL=0
+case "$CMD" in ensure) ;; status|install) ;; *) printf 'error: unknown command %s\nhelp: bin/sessrumnir-ensure.sh [status|ensure|install]\n' "$CMD" >&2; exit 2 ;; esac
+while [ $# -gt 0 ]; do case "$1" in --install) DO_INSTALL=1; shift ;; *) shift ;; esac; done
+[ "$CMD" = install ] && DO_INSTALL=1
+
+app_dir() { [ -d "$APP" ] && [ -f "$APP/package.json" ]; }
+deps_present() { [ -d "$APP/node_modules" ] && [ -x "$APP/node_modules/.bin/electron" ]; }
+built_present() { [ -f "$APP/out/main/index.js" ]; }
+
+status() {
+  local dir deps built electron
+  if app_dir; then dir="$APP"; else dir="absent"; fi
+  if deps_present; then deps="yes"; else deps="no"; fi
+  if built_present; then built="yes"; else built="no"; fi
+  if [ -x "$APP/node_modules/electron/dist/electron" ]; then electron="yes"; else electron="no"; fi
+  printf 'sessrumnir[1]{dir,deps,built,electron}:\n'
+  printf '  "%s","%s","%s","%s"\n' "$dir" "$deps" "$built" "$electron"
+  [ "$dir" = "absent" ] || [ "$deps" = "no" ] && return 1
+  return 0
+}
+
+npm_install() {
+  command -v npm >/dev/null 2>&1 || { printf 'error: npm not found — cannot install Sessrúmnir deps\nhelp: install node/npm\n' >&2; return 1; }
+  printf 'sessrumnir: installing dependencies (first run)…\n' >&2
+  ( cd "$APP" && npm install ) >/dev/null 2>&1 || return 1
+}
+
+# npm 11+ gates postinstall scripts (allowScripts), so Electron's binary is
+# often never downloaded even though the package installed. Heal that here —
+# the same remedy scripts/electron.sh uses: run the package's own postinstall,
+# then extract from the already-cached zip and write path.txt.
+ensure_electron_binary() {
+  local bin="$APP/node_modules/electron/dist/electron"
+  [ -x "$bin" ] && return 0
+  [ -d "$APP/node_modules/electron" ] || return 0
+  if [ -f "$APP/node_modules/electron/install.js" ]; then
+    ( cd "$APP" && node node_modules/electron/install.js ) >/dev/null 2>&1 || true
+  fi
+  [ -x "$bin" ] && return 0
+  local zip
+  zip="$(ls "$HOME"/.cache/electron/*/electron-v*-linux-*.zip 2>/dev/null | head -1)"
+  if [ -n "$zip" ] && command -v unzip >/dev/null 2>&1; then
+    mkdir -p "$APP/node_modules/electron/dist"
+    unzip -q -o "$zip" -d "$APP/node_modules/electron/dist" >/dev/null 2>&1 && \
+      printf 'electron' >"$APP/node_modules/electron/path.txt"
+  fi
+  [ -x "$bin" ]
+}
+
+build_app() {
+  printf 'sessrumnir: building the app (npm run build)…\n' >&2
+  ( cd "$APP" && npm run build ) >/dev/null 2>&1 || return 1
+}
+
+case "$CMD" in
+  status) status; exit $? ;;
+  install)
+    npm_install || { printf 'error: npm install failed — see apps/sessrumnir\n' >&2; exit 1; }
+    ensure_electron_binary || { printf 'error: Electron binary missing — run: cd apps/sessrumnir && node node_modules/electron/install.js\n' >&2; exit 1; }
+    build_app || { printf 'error: build failed — run: cd apps/sessrumnir && npm run build\n' >&2; exit 1; }
+    status; exit $? ;;
+  ensure)
+    if status >/dev/null 2>&1; then status; exit 0; fi
+    if [ "$DO_INSTALL" = 1 ]; then
+      npm_install || true
+      ensure_electron_binary || true
+      [ "$built_present" ] || build_app || true
+      status
+      exit $?
+    fi
+    status
+    printf 'sessrumnir: not ready — run `bin/sessrumnir-ensure.sh install`\n' >&2
+    exit 1 ;;
+esac

package/bin/sessrumnir-sync.sh

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# sessrumnir-sync.sh — pull a new pi-desktop release into the Sessrúmnir fork
+# without losing the Ymir delta. The law: upstream owns everything except the
+# Ymir-owned files; the branding rides on top and is re-applied by a true
+# 3-way git merge, never by clobbering.
+#
+#   bin/sessrumnir-sync.sh                       # sync to the version pinned in fork/PIN
+#   bin/sessrumnir-sync.sh <tag-or-commit>       # sync to an explicit upstream ref
+#   bin/sessrumnir-sync.sh --check [<ref>]       # dry-run: what would change (no writes)
+#   bin/sessrumnir-sync.sh --regen <ref>         # after hand-resolving conflicts: renumber PIN,
+#                                                # regenerate mods.patch, run the gate
+#
+# How a sync works (the fork-rebase):
+#   base   = pristine upstream tree at PIN        (what the fork was cut from)
+#   ours   = the branded fork as it sits now      (base + Ymir delta)
+#   theirs = pristine upstream tree at <ref>      (whatever the Allfather pulls)
+#   git merge base←ours + base←theirs  →  a true 3-way merge. Conflicts are
+#   left in the working tree for Brokk to resolve, never auto-resolved, never
+#   half-applied. Bare changes from upstream land; our branding survives where
+#   upstream did not touch the same lines; collisions are surfaced as markers.
+#
+# Exits 0 on a clean, gated sync; 2 on merge conflicts left for the operator;
+# 1 on any hard failure.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+APP="$ROOT/apps/sessrumnir"
+FORK="$APP/fork"
+UPSTREAM_REPO="${SESSRUMNIR_UPSTREAM:-https://github.com/zerwiz/pi-desktop.git}"
+OWNED_JSON="$FORK/owned.json"
+MODS_PATCH="$FORK/mods.patch"
+PIN_FILE="$FORK/PIN"
+
+MODE="sync"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --check) MODE="check"; shift ;;
+    --regen) MODE="regen"; shift ;;
+    *) break ;;
+  esac
+done
+TARGET="${1:-}"
+
+fail() { echo "✗ $*" >&2; exit 1; }
+step() { printf '\n▸ %s\n' "$*"; }
+
+# ─── Pin reading ──────────────────────────────────────────────────────────────
+read_pin() {
+  [[ -f "$PIN_FILE" ]] || fail "no PIN at $PIN_FILE — a full sync never happened yet"
+  local line hash
+  while IFS= read -r line; do
+    hash="${line%%#*}"
+    hash="${hash// /}"
+    [[ "$hash" =~ ^[0-9a-f]{7,40}$ ]] && { echo "$hash"; return; }
+  done < "$PIN_FILE"
+  fail "PIN file at $PIN_FILE holds no commit hash"
+}
+
+# ─── Named sets from owned.json ───────────────────────────────────────────────
+[[ -f "$OWNED_JSON" ]] || fail "owned.json missing — the fork contract is gone ($OWNED_JSON)"
+OWNED_FILES=()
+while IFS= read -r f; do OWNED_FILES+=("$f"); done < <(jq -r '.files[]' "$OWNED_JSON" 2>/dev/null || fail "owned.json unreadable — is jq installed?")
+GENERATED_PATHS=()
+while IFS= read -r f; do GENERATED_PATHS+=("$f"); done < <(jq -r '.generated[]' "$OWNED_JSON" 2>/dev/null)
+
+step "Sessrúmnir fork sync ($MODE)"
+echo "  upstream : $UPSTREAM_REPO"
+echo "  target   : ${TARGET:-$(read_pin)}"
+
+# ─── Fetch upstream ───────────────────────────────────────────────────────────
+SCRATCH="$(mktemp -d)"
+trap 'rm -rf "$SCRATCH"' EXIT
+step "cloning upstream into $SCRATCH/up"
+git clone "$UPSTREAM_REPO" "$SCRATCH/up" >/dev/null 2>&1 || fail "clone failed for $UPSTREAM_REPO"
+
+resolve_ref() { # <ref-or-empty> -> commit hash
+  local ref="${1:-}"; ref="${ref:-HEAD}"
+  ( cd "$SCRATCH/up" && git rev-parse --verify "$ref^{commit}" ) 2>/dev/null \
+    || fail "ref not found upstream: $ref"
+}
+
+THEIRS_COMMIT="$(resolve_ref "$TARGET")"
+THEIRS_SHORT="${THEIRS_COMMIT:0:10}"
+echo "  upstream HEAD: $THEIRS_SHORT ($(cd "$SCRATCH/up" && git log -1 --format=%s "$THEIRS_COMMIT"))"
+
+# ─── Materialise the three trees ──────────────────────────────────────────────
+pin_commit="$(read_pin 2>/dev/null || echo "")"
+BASE_COMMIT="$pin_commit"
+if [[ -z "$BASE_COMMIT" ]]; then
+  echo "  (no PIN yet — first sync; base := empty tree, every upstream file arrives)"
+  IS_FIRST_SYNC=1
+  BASE_COMMIT=""
+fi
+
+checkout_tree() { # <dir> <commit-or-empty>
+  local dir="$1" commit="$2"
+  if [[ -z "$commit" ]]; then
+    mkdir -p "$dir"
+  else
+    git -C "$SCRATCH/up" worktree add --detach "$dir" "$commit" >/dev/null 2>&1 \
+      || fail "cannot materialise $commit"
+  fi
+}
+
+checkout_tree "$SCRATCH/base" "$BASE_COMMIT"
+checkout_tree "$SCRATCH/theirs" "$THEIRS_COMMIT"
+ours=$APP  # the branded fork is the working tree itself
+
+# ─── Exclude map shared by every copy ─────────────────────────────────────────
+copy_tree() { # <src> <dst>   (rsync: refresh files, delete upstream removals)
+  local src="$1" dst="$2" ex=()
+  for f in "${GENERATED_PATHS[@]}" ".git" "fork"; do ex+=(--exclude="$f"); done
+  for f in "${OWNED_FILES[@]}"; do ex+=(--exclude="$f"); done
+  rsync -a --delete "${ex[@]}" "$src/" "$dst/"
+}
+
+# ─── --check: show what a sync would change ───────────────────────────────────
+if [[ "$MODE" == "check" ]]; then
+  step "--check: what a sync to $THEIRS_SHORT would change (no writes)"
+  local ex=()
+  for f in "${GENERATED_PATHS[@]}" ".git" "fork"; do ex+=(--exclude="$f"); done
+  for f in "${OWNED_FILES[@]}"; do ex+=(--exclude="$f"); done
+  rsync -a --delete --dry-run "${ex[@]}" "$SCRATCH/theirs/" "$APP/" 2>/dev/null \
+    | grep -E "^deleting|^>f" | head -60
+  echo
+  echo "  owned files and fork/ are never touched; upstream deletions are respected;"
+  echo "  branding rides in fork/mods.patch and is re-merged, not clobbered."
+  exit 0
+fi
+
+# ─── --regen: after hand-resolving conflicts ──────────────────────────────────
+if [[ "$MODE" == "regen" ]]; then
+  [[ -n "$TARGET" ]] || fail "--regen needs the upstream ref you synced to"
+  step "regenerating delta from resolved tree (base=$THEIRS_SHORT)"
+  # pristine base at target vs current (resolved) app tree, owned files excluded.
+  mkdir -p "$SCRATCH/out" && copy_tree "$SCRATCH/theirs" "$SCRATCH/out/base" 
+  mkdir -p "$SCRATCH/out/app" && copy_tree "$APP" "$SCRATCH/out/app"
+  ( cd "$SCRATCH/out" && diff -ruN base app > "$SCRATCH/mods.patch" 2>/dev/null || true )
+  [[ -s "$SCRATCH/mods.patch" ]] || fail "no delta between pristine $THEIRS_SHORT and app — nothing vendored?"
+  cp "$SCRATCH/mods.patch" "$MODS_PATCH"
+  cat > "$PIN_FILE" <<EOF
+# Upstream pi-desktop commit currently vendored into apps/sessrumnir
+$THEIRS_COMMIT   # $(cd "$SCRATCH/up" && git log -1 --format=%s "$THEIRS_COMMIT")
+$(cd "$SCRATCH/up" && git describe --tags "$THEIRS_COMMIT" 2>/dev/null || echo "(no tag at $THEIRS_SHORT)")
+EOF
+  echo "  PIN → $THEIRS_SHORT; mods.patch regenerated ($(wc -l < "$SCRATCH/mods.patch") lines)"
+  step "gate: install, typecheck, lint, build"
+  ( cd "$APP" && npm install --no-audit --no-fund >/dev/null 2>&1 ) || fail "npm install failed"
+  ( cd "$APP" && npm run typecheck 2>&1 | tail -5 ) || fail "typecheck failed"
+  ( cd "$APP" && npm run lint 2>&1 | tail -8 ) || fail "lint failed"
+  ( cd "$APP" && npm run build 2>&1 | tail -5 ) || fail "build failed"
+  echo
+  echo "✓ sync sealed — Sessrúmnir now vendors $THEIRS_SHORT"
+  echo "  next: stage the tree, review, open a PR (human seals merges)."
+  exit 0
+fi
+
+# ─── Sync: the fork-rebase ────────────────────────────────────────────────────
+step "materialising the three trees"
+checkout_tree "$SCRATCH/ours.tmp" "$BASE_COMMIT" 2>/dev/null || true
+copy_tree "$APP" "$SCRATCH/ours.tmp"  # ours = branded fork as it sits (owned files ride along)
+
+step "building the merge in a scratch repo"
+MERGE="$SCRATCH/merge"
+git init -q "$MERGE"
+cd "$MERGE"
+git config user.name "Brokk" >/dev/null 2>&1 || true
+git config user.email "brokk@ymir.local" >/dev/null 2>&1 || true
+export GIT_AUTHOR_NAME="Brokk" GIT_AUTHOR_EMAIL="brokk@ymir.local"
+export GIT_COMMITTER_NAME="Brokk" GIT_COMMITTER_EMAIL="brokk@ymir.local"
+
+# base commit (pristine upstream at PIN)
+rsync -a --exclude=.git "$SCRATCH/base/" ./
+git add -A -f; BASE_T=$(git write-tree); BASE_C=$(git commit-tree "$BASE_T" -m "base")
+# clean worktree + index for ours (branded fork, owned+fork excluded by design)
+git rm -rf --quiet . 2>/dev/null; git clean -fd >/dev/null 2>&1
+rsync -a --exclude=.git "$SCRATCH/ours.tmp/" ./
+git add -A -f; OURS_T=$(git write-tree); OURS_C=$(git commit-tree "$OURS_T" -p "$BASE_C" -m "ours")
+# clean again for theirs (new upstream)
+git rm -rf --quiet . 2>/dev/null; git clean -fd >/dev/null 2>&1
+rsync -a --exclude=.git "$SCRATCH/theirs/" ./
+git add -A -f; THEIRS_T=$(git write-tree); THEIRS_C=$(git commit-tree "$THEIRS_T" -p "$BASE_C" -m "theirs")
+# branches + merge
+git update-ref refs/heads/ours "$OURS_C"
+git update-ref refs/heads/theirs "$THEIRS_C"
+git symbolic-ref HEAD refs/heads/ours
+git checkout -f ours >/dev/null 2>&1 || true
+
+step "merging upstream $THEIRS_SHORT into the branded fork (3-way)"
+git merge --no-commit --no-ff theirs >merge.log 2>&1 || true
+grep -E "CONFLICT|Automatic merge failed" merge.log || true
+
+# conflicts?
+CONFLICTED="$(git diff --name-only --diff-filter=U)"
+if [[ -n "$CONFLICTED" ]]; then
+  echo
+  echo "⚠ merge conflicts — resolving in apps/sessrumnir before sealing:" >&2
+  echo "$CONFLICTED" | sed 's/^/    /' >&2
+  # lay the merged tree (conflict markers included) into the fork so resolution
+  # happens in the real working tree; owned files and fork/ are never touched.
+  copy_tree "$MERGE" "$APP"
+  echo >&2
+  echo "  the merged tree with conflict markers is now the working tree under" >&2
+  echo "  apps/sessrumnir. Branding is ours; upstream-only change is theirs. A" >&2
+  echo "  deleted file either side re-added by upstream means: decide. Present" >&2
+  echo "  the changed files and resolve by hand (owned files carry the Ymir text)." >&2
+  echo "  When done, re-run the merge and seal with:" >&2
+  echo '    bin/sessrumnir-sync.sh --regen '"$THEIRS_SHORT" >&2
+  exit 2
+fi
+
+step "sealing sync (no conflicts)"
+copy_tree "$MERGE" "$APP"   # merged tree back into the fork (owned + fork/ excluded separately)
+step "writing PIN"
+cat > "$PIN_FILE" <<EOF
+# Upstream pi-desktop commit currently vendored into apps/sessrumnir
+$THEIRS_COMMIT   # $(cd "$SCRATCH/up" && git log -1 --format=%s "$THEIRS_COMMIT")
+$(cd "$SCRATCH/up" && git describe --tags "$THEIRS_COMMIT" 2>/dev/null || echo "(no tag at $THEIRS_SHORT)")
+EOF
+echo "  pinned $THEIRS_SHORT"
+
+step "regenerating mods.patch (pristine $THEIRS_SHORT → branded fork)"
+mkdir -p "$SCRATCH/out/base" "$SCRATCH/out/app"
+copy_tree "$SCRATCH/theirs" "$SCRATCH/out/base"
+copy_tree "$APP" "$SCRATCH/out/app"
+( cd "$SCRATCH/out" && diff -ruN base app > "$SCRATCH/mods.patch" 2>/dev/null || true )
+cp "$SCRATCH/mods.patch" "$MODS_PATCH"
+
+step "gate: install, typecheck, lint, build"
+( cd "$APP" && npm install --no-audit --no-fund >/dev/null 2>&1 ) || fail "npm install failed"
+( cd "$APP" && npm run typecheck 2>&1 | tail -5 ) || fail "typecheck failed"
+( cd "$APP" && npm run lint 2>&1 | tail -8 ) || fail "lint failed"
+( cd "$APP" && npm run build 2>&1 | tail -5 ) || fail "build failed"
+
+echo
+echo "✓ sync complete — Sessrúmnir now vendors $THEIRS_SHORT"
+echo "  next: review the diff, then open a PR (human seals merges)."

package/bin/sessrumnir.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# sessrumnir.sh — launch the Sessrúmnir desktop GUI (the seat-hall).
+# Ensures deps + build are present (bin/sessrumnir-ensure.sh), then raises the
+# Electron window via the app's own launcher. Galdr-style TOON.
+#
+# Usage:
+#   sessrumnir.sh [start] [path]     # launch (deps installed on first run)
+#   sessrumnir.sh start ~/my-project # launch with a workspace
+#   sessrumnir.sh status
+#   sessrumnir.sh stop
+#   sessrumnir.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+APP="$ROOT/apps/sessrumnir"
+PID_FILE="$ROOT/state/sessrumnir.pid"
+LOG_FILE="$ROOT/state/sessrumnir.log"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+ACTION="${1:-start}"; shift || true
+WORKSPACE="${1-}"
+
+# The launcher spawns Electron as its child; track the real Electron by its
+# command line — the Sessrúmnir user-data-dir is a unique, stable identity.
+view_pids() {
+  pgrep -f "electron/dist/electron.*sessrumnir" 2>/dev/null || true
+}
+is_running() { [ -n "$(view_pids)" ]; }
+
+# Raise the running window. The desktop-placement rule may have opened it on its
+# own numbered desktop (desktop-place.sh), so a launch from elsewhere would
+# otherwise show nothing — the focus dispatch also switches to where it sits.
+# Omarchy configures Hyprland in Lua, so the dispatch is a Lua expression (the
+# classic `focuswindow class:...` form does not parse).
+focus_window() {
+  command -v hyprctl >/dev/null 2>&1 || return 0
+  hyprctl dispatch "hl.dsp.focus({window=\"class:^sessrumnir\$\"})" >/dev/null 2>&1 || true
+}
+
+case "$ACTION" in
+  status)
+    if is_running; then
+      p="$(view_pids | head -1)"
+      printf 'sessrumnir[1]{state,pid}:\n  "up",%s\n' "$p"
+    else
+      printf 'sessrumnir[1]{state,pid}:\n  "down",0\n'
+    fi
+    exit 0 ;;
+  stop)
+    pids="$(view_pids)"
+    if [ -n "$pids" ]; then
+      printf '%s\n' "$pids" | while IFS= read -r p; do [ -n "$p" ] && kill "$p" 2>/dev/null || true; done
+      printf 'sessrumnir: stopped pid(s)=%s\n' "$(printf '%s' "$pids" | tr '\n' ',' | sed 's/,$//')"
+    fi
+    rm -f "$PID_FILE"
+    printf 'sessrumnir: stopped\n'
+    exit 0 ;;
+  start) ;;
+  *) printf 'error: unknown action %s\nhelp: bin/sessrumnir.sh [start|status|stop]\n' "$ACTION" >&2; exit 2 ;;
+esac
+
+if is_running; then
+  focus_window
+  printf 'sessrumnir[1]{state,pid}:\n  "already up",%s\n' "$(view_pids | head -1)"
+  exit 0
+fi
+
+"$SCRIPT_DIR/sessrumnir-ensure.sh" ensure --install >/dev/null 2>&1 || {
+  printf 'error: Sessrúmnir is not ready — run bin/sessrumnir-ensure.sh install\n' >&2
+  exit 1
+}
+
+mkdir -p "$ROOT/state"
+args=()
+[ -n "$WORKSPACE" ] && args+=("$WORKSPACE")
+
+nohup node "$APP/bin/sessrumnir.js" "${args[@]}" >"$LOG_FILE" 2>&1 < /dev/null &
+echo $! >"$PID_FILE"
+
+i=0
+for i in $(seq 1 30); do [ -n "$(view_pids)" ] && break; sleep 0.5; done
+
+if is_running; then
+  focus_window
+  printf 'sessrumnir[1]{state,pid}:\n  "up",%s\n' "$(view_pids | head -1)"
+else
+  printf 'error: Sessrúmnir failed to start; see %s\n' "${LOG_FILE#"$ROOT"/}" >&2
+  exit 1
+fi