@zerwiz/ymir 0.1.3 → 0.1.5

package/bin/workspace-provision.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# workspace-provision.sh — carve one workspace for the operator. Single tenant:
+# a workspace is a running scope (personal | work) over a set of knowledge
+# domains. A work workspace attaches to its company's container.
+#
+# Usage:
+#   bin/workspace-provision.sh <name> --kind work|personal [--domains a,b,c] [--company <slug>]
+#   bin/workspace-provision.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=bin/hoard-lib.sh
+. "$SCRIPT_DIR/hoard-lib.sh"
+WORKSPACE="$ROOT/workspace"
+DEFAULT_WORK="company,marketing,development,life"
+DEFAULT_PERSONAL="me,life,development"
+
+case "${1-}" in -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;; -h|--help|"") sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; esac
+
+NAME="${1-}"; shift || true
+[ -n "$NAME" ] || { printf 'error: workspace needs a name\nhelp: bin/workspace-provision.sh <name> --kind work|personal\n' >&2; exit 2; }
+case "$NAME" in *[!a-z0-9-]*|'') printf 'error: name must be a lowercase slug [a-z0-9-]\n' >&2; exit 2 ;; esac
+
+KIND=""; DOMAINS=""; COMPANY=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --kind) KIND=${2-}; shift 2 ;;
+    --domains) DOMAINS=${2-}; shift 2 ;;
+    --company) COMPANY=${2-}; shift 2 ;;
+    *) printf 'error: unknown flag %s\n' "$1" >&2; exit 2 ;;
+  esac
+done
+case "$KIND" in
+  work)
+    [ -n "$COMPANY" ] || { printf 'error: --kind work needs --company <slug>\nhelp: the company is yours to name; Ymir ships no default\n' >&2; exit 2; }
+    DOMAINS=${DOMAINS:-$DEFAULT_WORK} ;;
+  personal) DOMAINS=${DOMAINS:-$DEFAULT_PERSONAL} ;;
+  *) printf 'error: --kind must be work or personal\n' >&2; exit 2 ;;
+esac
+
+mkdir -p "$WORKSPACE"
+made=0
+IFS=',' read -ra DOMARR <<<"$DOMAINS"
+for d in "${DOMARR[@]}"; do
+  d="$(printf '%s' "$d" | tr -d ' ')"
+  [ -n "$d" ] || continue
+  if [ ! -d "$WORKSPACE/$NAME/$d" ]; then mkdir -p "$WORKSPACE/$NAME/$d"; made=$((made+1)); fi
+done
+mkdir -p "$WORKSPACE/$NAME/memory/daily"
+
+# Register (idempotent) in workspaces.yaml.
+hoard_root _hoard
+reg="$_hoard/identity/workspaces.yaml"
+[ -f "$reg" ] || reg="$WORKSPACE/workspaces.yaml"
+if [ ! -f "$reg" ]; then printf 'workspaces:\n' >"$reg"; fi
+if grep -qE "^  - id: ${NAME}$" "$reg" 2>/dev/null; then
+  registered="exists"
+else
+  {
+    printf '  - id: %s\n' "$NAME"
+    printf '    name: %s\n' "$(printf '%s' "$NAME" | awk '{print toupper(substr($0,1,1)) substr($0,2)}')"
+    printf '    kind: %s\n' "$KIND"
+    [ "$KIND" = work ] && printf '    company: %s\n' "$COMPANY"
+    printf '    domains: [%s]\n' "$(printf '%s' "$DOMAINS" | sed 's/,/, /g')"
+  } >>"$reg"
+  registered="added"
+fi
+
+# A work workspace attaches to the company's container root.
+container="—"
+if [ "$KIND" = work ]; then
+  container="svartalfaheim/$COMPANY"
+  mkdir -p "$ROOT/$container/companies" "$ROOT/$container/workspace"
+fi
+
+printf 'workspace[1]{id,kind,company,domains,dirs,registry,container}:\n'
+printf '  "%s","%s","%s","%s",%s,"%s","%s"\n' \
+  "$NAME" "$KIND" "${COMPANY:-—}" "$DOMAINS" "$made" "$registered" "$container"

package/bin/workspace-rag.sh

@@ -0,0 +1,150 @@
+#!/usr/bin/env bash
+# workspace-rag.sh — memory over the realm workspaces (W0038).
+#
+# Hybrid recall across `workspace/` and `svartalfaheim/<realm>/workspace/*`: index
+# Markdown into the well, query by term overlap, and expose an entity graph from
+# `workspace/memory/entity_graph/`. Local, deterministic, no network. Galdr TOON.
+#
+# Usage:
+#   workspace-rag.sh index [--realm <realm>]
+#   workspace-rag.sh query <terms...> [--k N]
+#   workspace-rag.sh entities
+#   workspace-rag.sh graph [--entity X]
+#   workspace-rag.sh --version
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+STORE="$ROOT/.agents/memory/well/workspace.jsonl"
+REALM_FILE="$ROOT/data/realm.md"
+DEFAULT_REALM="$(head -n1 "$REALM_FILE" 2>/dev/null | tr -d '[:space:]')"
+# Never assume the company's slug: resolve the operator's realm neutrally.
+if [ -z "$DEFAULT_REALM" ]; then . "$SCRIPT_DIR/realm-lib.sh"; ymir_active_realm "$ROOT" DEFAULT_REALM; fi
+
+# Portable xargs: GNU's -r (skip the command on empty input) does not exist in
+# BSD/macOS xargs. Read the input first, then run only when there is something.
+xargs_skip_empty() {  # <args...>
+  local input
+  input=$(cat)
+  [ -n "$input" ] || return 0
+  printf '%s\n' "$input" | xargs "$@"
+}
+
+usage() { sed -n '2,14p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+[ -e "$STORE" ] || { mkdir -p "$(dirname "$STORE")"; : >"$STORE"; }
+
+index_cmd() {
+  local realm=$DEFAULT_REALM
+  while [ $# -gt 0 ]; do case "$1" in --realm) realm=${2-}; shift 2 ;; *) shift ;; esac; done
+  local n
+  # One pass, one Python process: the store is read into `seen` a single time and
+  # every file is walked here, so dedupe is O(entries) not O(files x store).
+  n=$(python3 - "$ROOT" "$realm" "$STORE" <<'PY'
+import sys, os, json, hashlib, datetime
+root, realm, store = sys.argv[1:4]
+seen=set()
+try:
+    for line in open(store, encoding='utf-8', errors='ignore'):
+        try:
+            h=json.loads(line).get('hash')
+            if h: seen.add(h)
+        except: pass
+except FileNotFoundError: pass
+roots=[os.path.join(root,'workspace'),
+       os.path.join(root,'svartalfaheim',realm,'workspace'),
+       os.path.join(root,'midgard')]
+files=[]
+for r in roots:
+    for dp,_,fns in os.walk(r):
+        for fn in fns:
+            if fn.endswith('.md'): files.append(os.path.join(dp,fn))
+files.sort()
+now=datetime.datetime.now(datetime.timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')
+added=0
+with open(store,'a',encoding='utf-8') as out:
+    for f in files:
+        try: text=open(f, encoding='utf-8', errors='ignore').read()
+        except: continue
+        rel=os.path.relpath(f, root)
+        chunks=[]; head=''; buf=[]
+        for line in text.split('\n'):
+            if line.startswith('#'):
+                body='\n'.join(buf).strip()
+                if body: chunks.append((head,body))
+                head=line.lstrip('# ').strip(); buf=[]
+            else: buf.append(line)
+        body='\n'.join(buf).strip()
+        if body: chunks.append((head,body))
+        for head,body in chunks:
+            content=(head+'\n'+body).strip()
+            if len(content)<40: continue
+            h=hashlib.sha256(content.encode()).hexdigest()
+            if h in seen: continue
+            seen.add(h)
+            rec={'timestamp':now,'source':rel,'tags':['workspace',realm],'content':content[:2000],'hash':h}
+            out.write(json.dumps(rec)+'\n'); added+=1
+print(added)
+PY
+)
+  n=${n:-0}
+  printf 'indexed[1]{realm,store,added,entries}:\n  "%s","%s",%s,%s\n' "$realm" "${STORE#"$ROOT"/}" "$n" "$(wc -l <"$STORE" | tr -d ' ')"
+}
+
+query_cmd() {
+  local k=5 terms=""
+  while [ $# -gt 0 ]; do case "$1" in --k) k=${2-5}; shift 2 ;; *) terms="$terms $1"; shift ;; esac; done
+  terms=$(printf '%s' "$terms" | sed 's/^ *//')
+  [ -n "$terms" ] || { printf 'error: query needs terms\n' >&2; exit 2; }
+  python3 - "$STORE" "$terms" "$k" <<'PY'
+import json,sys,re
+store,terms,k=sys.argv[1],sys.argv[2].lower(),int(sys.argv[3])
+words=[w for w in re.split(r'\W+',terms) if len(w)>2] or [terms]
+rows=[]
+for line in open(store, encoding='utf-8', errors='ignore'):
+    try: e=json.loads(line)
+    except: continue
+    c=e.get('content','').lower()
+    score=sum(c.count(w) for w in words)
+    if score>0: rows.append((score,e))
+rows.sort(key=lambda r:-r[0])
+print(f"recall[{min(len(rows),k)}]{{score,source,title}}:")
+for sc,e in rows[:k]:
+    t=(e.get('content','').split('\n')[0] or '').replace('#','').strip()[:90]
+    print(f"  {sc},\"{e.get('source','workspace')}\",\"{t}\"")
+PY
+}
+
+entity_files() { find "$ROOT/workspace" "$ROOT/svartalfaheim/$DEFAULT_REALM/workspace" -path '*/entity_graph/*' -name '*.md' 2>/dev/null; }
+
+entities_cmd() {
+  # Filenames are passed to grep as argv by xargs (never through a shell), so a
+  # path containing quotes or $(…) can never become code.
+  printf 'entities[%s]{entity,source}:\n' "$(entity_files | xargs_skip_empty -I{} grep -ohE '\[\[[^]]+\]\]' {} 2>/dev/null | sed 's/\[\[//;s/\]\]//' | sort -u | wc -l | tr -d ' ')"
+  entity_files | xargs_skip_empty -I{} grep -ohE '\[\[[^]]+\]\]' {} 2>/dev/null | sed 's/\[\[//;s/\]\]//' | sort -u | while read -r e; do [ -n "$e" ] && printf '  "%s","entity_graph"\n' "$e"; done
+}
+
+graph_cmd() {
+  local ent=""; while [ $# -gt 0 ]; do case "$1" in --entity) ent=${2-}; shift 2 ;; *) shift ;; esac; done
+  printf 'graph[%s]{from,to}:\n' "$(entity_files | xargs_skip_empty -I{} grep -ohE '\[\[[^]]+\]\] *[-=]> *\[\[[^]]+\]\]' {} 2>/dev/null | wc -l | tr -d ' ')"
+  entity_files | xargs_skip_empty -I{} grep -ohE '\[\[[^]]+\]\] *[-=]> *\[\[[^]]+\]\]' {} 2>/dev/null | while IFS= read -r line; do
+    from=$(printf '%s' "$line" | sed -E 's/\[\[([^]]+)\]\].*/\1/')
+    to=$(printf '%s' "$line" | sed -E 's/.*\[\[([^]]+)\]\]/\1/')
+    [ -n "$ent" ] && { [ "$from" = "$ent" ] || [ "$to" = "$ent" ] || continue; }
+    printf '  "%s","%s"\n' "$from" "$to"
+  done
+}
+
+case "$CMD" in
+  index) index_cmd "$@" ;;
+  query|recall) query_cmd "$@" ;;
+  entities) entities_cmd ;;
+  graph) graph_cmd "$@" ;;
+  *) printf 'error: unknown command %s\nhelp: bin/workspace-rag.sh [index|query|entities|graph|--version]\n' "$CMD" >&2; exit 2 ;;
+esac

package/bin/wyrd-db.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# wyrd-db.sh — the database layer (W0040). Applies the platform schema and reports
+# its state via psql. The input is `midgard/infrastructure/db/schema.sql`; files
+# stay the raw record, this is the queryable mirror. Galdr-style TOON.
+#
+# Usage:
+#   wyrd-db.sh status
+#   wyrd-db.sh apply
+#   wyrd-db.sh psql [args...]
+#   wyrd-db.sh --version
+#
+# Env: DATABASE_URL (postgres://user:pass@host:port/db). Absent → uses psql defaults.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+SCHEMA="$ROOT/midgard/infrastructure/db/schema.sql"
+
+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
+command -v psql >/dev/null 2>&1 || { printf 'error: psql not installed\nhelp: install the postgres client\n' >&2; exit 1; }
+[ -f "$SCHEMA" ] || { printf 'error: schema missing: %s\n' "$SCHEMA" >&2; exit 1; }
+PSQL=(psql -v ON_ERROR_STOP=1)
+[ -n "${DATABASE_URL:-}" ] && PSQL=("${PSQL[@]}" "$DATABASE_URL")
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  apply)
+    if "${PSQL[@]}" -q -f "$SCHEMA" >/dev/null 2>&1; then
+      printf 'wyrd[1]{schema,status}:\n  "midgard/infrastructure/db/schema.sql","applied"\n'
+    else
+      printf 'error: schema apply failed\nhelp: check DATABASE_URL and that Postgres is reachable (docker-compose up postgres)\n' >&2
+      exit 1
+    fi
+    ;;
+  status)
+    n=$("${PSQL[@]}" -tAc "select count(*) from information_schema.tables where table_schema='public'" 2>/dev/null) || { printf 'wyrd[1]{db,status}:\n  "%s","unreachable"\n' "${DATABASE_URL:-psql-default}"; exit 1; }
+    printf 'wyrd[1]{db,tables,status}:\n  "%s",%s,"up"\n' "${DATABASE_URL:-psql-default}" "$n"
+    ;;
+  psql)
+    exec "${PSQL[@]}" "$@"
+    ;;
+  *) printf 'error: unknown command %s\nhelp: bin/wyrd-db.sh [status|apply|psql|--version]\n' "$CMD" >&2; exit 2 ;;
+esac

package/bin/yggdrasil.sh

@@ -0,0 +1,152 @@
+#!/usr/bin/env bash
+# yggdrasil.sh — the worktree manager (Yggdrasil, the world-tree).
+#
+# Zero-collision parallel work: each task gets its own `.yggdrasil/<id>/` checkout
+# on its own branch, created, listed, merged, and cleaned up explicitly. Galdr-style:
+# TOON output, structured errors, no prompts, --version fast path.
+#
+# Usage:
+#   yggdrasil.sh create <id> [--repo <path>] [--base <branch>]
+#   yggdrasil.sh list   [--repo <path>]
+#   yggdrasil.sh status <id> [--repo <path>]
+#   yggdrasil.sh merge  <id> [--repo <path>] [--into <branch>] [--no-ff]
+#   yggdrasil.sh cleanup <id> [--repo <path>] [--force]
+#   yggdrasil.sh pool   <treehouse args…>   # the reusable worktree pool engine
+#   yggdrasil.sh --version
+#
+# Engine: the reusable worktree pool is **treehouse**
+# (github.com/kunchenguid/treehouse); this script is the Norse shell. `create`
+# keeps an explicit, named branch for merge/cleanup; `pool` delegates to the
+# treehouse pool directly.
+#
+# Exit: 0 ok, 1 error, 2 usage.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO="${YGGDRASIL_REPO:-$(pwd)}"
+WT=".yggdrasil"
+PREFIX="yggdrasil"
+
+usage() { sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; }
+
+CMD="${1-}"; shift || true
+case "$CMD" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") usage; exit 0 ;;
+esac
+
+# `pool` delegates straight to the treehouse pool engine (no branch bookkeeping).
+if [ "$CMD" = "pool" ]; then
+  command -v treehouse >/dev/null 2>&1 || { printf 'error: treehouse not installed\nhelp: bin/ymir-install.sh\n' >&2; exit 1; }
+  exec treehouse "$@"
+fi
+
+ID=""
+BASE=""
+INTO=""
+FORCE=0
+NOFF=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --repo) REPO=${2-}; shift 2 ;;
+    --base) BASE=${2-}; shift 2 ;;
+    --into) INTO=${2-}; shift 2 ;;
+    --force) FORCE=1; shift ;;
+    --no-ff) NOFF=1; shift ;;
+    -*) printf 'error: unknown flag %s\nhelp: bin/yggdrasil.sh %s [--repo <p>]\n' "$1" "$CMD" >&2; exit 2 ;;
+    *) ID=$1; shift ;;
+  esac
+done
+
+[ -d "$REPO" ] || { printf 'error: repo not found: %s\nhelp: pass --repo <path>\n' "$REPO" >&2; exit 1; }
+REPO="$(cd "$REPO" && pwd)"
+git -C "$REPO" rev-parse --git-dir >/dev/null 2>&1 || { printf 'error: not a git repository: %s\n' "$REPO" >&2; exit 1; }
+BRANCH="$PREFIX/$ID"
+WTPATH="$REPO/$WT/$ID"
+
+default_branch() {
+  local db
+  db="$(git -C "$REPO" symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')"
+  [ -n "$db" ] || db="$(git -C "$REPO" branch --show-current 2>/dev/null)"
+  [ -n "$db" ] || db=main
+  printf '%s' "$db"
+}
+
+case "$CMD" in
+  create)
+    [ -n "$ID" ] || { printf 'error: create needs an id\nhelp: bin/yggdrasil.sh create <id>\n' >&2; exit 2; }
+    case "$ID" in *[!A-Za-z0-9._-]*) printf 'error: unsafe id: %s\n' "$ID" >&2; exit 2 ;; esac
+    if [ -e "$WTPATH" ] || git -C "$REPO" show-ref --verify --quiet "refs/heads/$BRANCH"; then
+      printf 'error: worktree already exists: %s\nhelp: bin/yggdrasil.sh list\n' "$BRANCH" >&2; exit 1
+    fi
+    BASE="${BASE:-$(default_branch)}"
+    mkdir -p "$REPO/$WT"
+    git -C "$REPO" worktree add -b "$BRANCH" "$WTPATH" "$BASE" >/dev/null 2>&1 || { printf 'error: git worktree add failed (base %s)\n' "$BASE" >&2; exit 1; }
+    printf 'worktree[1]{id,branch,path,base}:\n  "%s","%s","%s","%s"\n' "$ID" "$BRANCH" "$WT/$ID" "$BASE"
+    ;;
+
+  list)
+    n=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | awk -v wt="$WT" '/^worktree /{ if ($2 ~ ("/" wt "/")) c++ } END { print c+0 }')
+    printf 'worktrees[%s]{id,branch,path,head}:\n' "$n"
+    git -C "$REPO" worktree list --porcelain 2>/dev/null | awk -v repo="$REPO" -v wt="$WT" '
+      /^worktree /{p=$2}
+      /^branch /{b=$2; sub("refs/heads/","",b)}
+      /^HEAD /{h=$2}
+      /^$/{ if (p ~ ("/" wt "/")) { id=p; sub(".*/","",id); printf "  \"%s\",\"%s\",\"%s\",\"%s\"\n", id, b, p, substr(h,1,8) } }
+    '
+    ;;
+
+  status)
+    [ -n "$ID" ] || { printf 'error: status needs an id\n' >&2; exit 2; }
+    [ -e "$WTPATH" ] || { printf 'error: no worktree %s\nhelp: bin/yggdrasil.sh list\n' "$ID" >&2; exit 1; }
+    dirty=$(git -C "$WTPATH" status --porcelain 2>/dev/null | wc -l | tr -d ' ')
+    head=$(git -C "$WTPATH" rev-parse --short HEAD 2>/dev/null)
+    ahead=$(git -C "$REPO" rev-list --count "$(default_branch)..$BRANCH" 2>/dev/null || echo 0)
+    printf 'status[1]{id,branch,head,dirty,ahead}:\n  "%s","%s","%s",%s,%s\n' "$ID" "$BRANCH" "$head" "$dirty" "$ahead"
+    ;;
+
+  merge)
+    [ -n "$ID" ] || { printf 'error: merge needs an id\n' >&2; exit 2; }
+    [ -e "$WTPATH" ] || { printf 'error: no worktree %s\n' "$ID" >&2; exit 1; }
+    dirty=$(git -C "$WTPATH" status --porcelain | wc -l | tr -d ' ')
+    if [ "$dirty" != "0" ]; then
+      printf 'error: worktree %s has unlanded changes (%s)\nhelp: commit or discard them first — never merge over unlanded work\n' "$ID" "$dirty" >&2
+      exit 1
+    fi
+    INTO="${INTO:-$(default_branch)}"
+    cur=$(git -C "$REPO" branch --show-current)
+    if [ "$cur" != "$INTO" ]; then
+      if git -C "$REPO" show-ref --verify --quiet "refs/heads/$INTO"; then
+        git -C "$REPO" checkout "$INTO" >/dev/null 2>&1 || { printf 'error: cannot checkout %s (dirty tree?)\n' "$INTO" >&2; exit 1; }
+      else
+        printf 'error: target branch %s not found\n' "$INTO" >&2; exit 1
+      fi
+    fi
+    if [ "$NOFF" = 1 ]; then
+      git -C "$REPO" merge --no-ff "$BRANCH" >/dev/null 2>&1 || { printf 'error: merge conflict — resolve manually\n' >&2; exit 1; }
+    else
+      git -C "$REPO" merge --ff-only "$BRANCH" >/dev/null 2>&1 || git -C "$REPO" merge --no-ff "$BRANCH" >/dev/null 2>&1 || { printf 'error: merge failed\n' >&2; exit 1; }
+    fi
+    printf 'merged[1]{id,into}:\n  "%s","%s"\n' "$ID" "$INTO"
+    ;;
+
+  cleanup)
+    [ -n "$ID" ] || { printf 'error: cleanup needs an id\n' >&2; exit 2; }
+    if [ -e "$WTPATH" ]; then
+      dirty=$(git -C "$WTPATH" status --porcelain | wc -l | tr -d ' ')
+      if [ "$dirty" != "0" ] && [ "$FORCE" != "1" ]; then
+        printf 'error: worktree %s has unlanded changes (%s)\nhelp: bin/yggdrasil.sh cleanup %s --force  (only after the Allfather approves discarding)\n' "$ID" "$dirty" "$ID" >&2
+        exit 1
+      fi
+      git -C "$REPO" worktree remove ${FORCE:+--force} "$WTPATH" >/dev/null 2>&1 || true
+    fi
+    git -C "$REPO" worktree prune >/dev/null 2>&1 || true
+    git -C "$REPO" branch -D "$BRANCH" >/dev/null 2>&1 || true
+    printf 'cleaned[1]{id,branch}:\n  "%s","%s"\n' "$ID" "$BRANCH"
+    ;;
+
+  *)
+    printf 'error: unknown command %s\nhelp: bin/yggdrasil.sh [-v|create|list|status|merge|cleanup]\n' "$CMD" >&2
+    exit 2 ;;
+esac

package/bin/ymir-edit.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# ymir-edit.sh — open a file in the Allfather's editor, on its own desktop.
+#
+# Why a wrapper: an editor window that lands on the desktop you are working on
+# steals the place you were reading. Ymir's law for its own windows is "own
+# numbered desktop, preferring an empty one" (bin/desktop-place.sh), and the
+# editor deserves the same treatment — open the file, then move that window off
+# to a free desktop so the work you were doing stays where it was.
+#
+# This is the value Pi's Open Editor extension should resolve for $EDITOR:
+#     export EDITOR="bin/ymir-edit.sh"
+# It accepts the same shape a normal editor does: `ymir-edit.sh <path>`.
+#
+# Usage:
+#   bin/ymir-edit.sh <path>          # open, then move to a free desktop
+#   bin/ymir-edit.sh --desktop <n> <path>
+#   bin/ymir-edit.sh --here <path>   # open on the current desktop (no move)
+#   bin/ymir-edit.sh --version
+#
+# Env:
+#   YMIR_EDITOR          the real editor (default: code, else nvim, else vi)
+#   YMIR_EDITOR_DESKTOP  'free' (default, an empty desktop) | 'here' | a number
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+case "${1-}" in
+  -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+  -h|--help|"") sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+esac
+
+MODE="${YMIR_EDITOR_DESKTOP:-free}"
+case "${1-}" in
+  --desktop) MODE=${2-}; shift 2 ;;
+  --here) MODE=here; shift ;;
+esac
+TARGET="${1:-}"
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# The real editor: an explicit override, else the first that exists. Never a
+# bare 'vi' — a host may have only nvim (this machine does).
+pick_editor() {
+  if [ -n "${YMIR_EDITOR:-}" ]; then printf '%s' "$YMIR_EDITOR"; return 0; fi
+  for e in code cursor zed subl nvim vim hx helix nano micro emacs; do
+    have "$e" && { printf '%s' "$e"; return 0; }
+  done
+  printf 'vi'
+}
+
+# Is this editor a GUI one (safe to launch detached and move)?
+is_gui() {
+  case "$(basename "$1")" in
+    code|code-insiders|codium|cursor|windsurf|subl|sublime_text|mate|atom|gedit|kate|zed) return 0 ;;
+  esac
+  return 1
+}
+
+# An empty numbered desktop, preferring the lowest free one. Mirrors
+# bin/desktop-place.sh's rule: on Omarchy the numbered desktops are the screens.
+free_desktop() {
+  command -v hyprctl >/dev/null 2>&1 || return 1
+  hyprctl workspaces -j 2>/dev/null | python3 -c '
+import json,sys
+try:
+    d=json.load(sys.stdin)
+except Exception:
+    sys.exit(0)
+used={w.get("id") for w in d if w.get("windows",0)>0}
+for n in range(1,11):
+    if n not in used:
+        print(n); break
+' 2>/dev/null
+}
+
+move_window_to() {  # <desktop> <class-regex>
+  local d=$1 cls=$2
+  command -v hyprctl >/dev/null 2>&1 || return 1
+  # Hyprland 0.56 here wraps dispatch in Lua, so the comma form can fail; try
+  # both the classic and the keyword form, and report honestly if neither lands.
+  hyprctl dispatch movetoworkspacesilent "$d,class:$cls" >/dev/null 2>&1 && return 0
+  hyprctl keyword windowrulev2 "workspace $d silent,class:$cls" >/dev/null 2>&1 || true
+  return 0
+}
+
+[ -n "$TARGET" ] || { printf 'error: ymir-edit needs a path\nhelp: bin/ymir-edit.sh <path>\n' >&2; exit 2; }
+
+EDITOR_BIN="$(pick_editor)"
+EDITOR_BASE="$(basename "$EDITOR_BIN")"
+
+if ! is_gui "$EDITOR_BIN"; then
+  # A terminal editor cannot be moved to another desktop: it lives in this
+  # terminal. Say so instead of pretending, and open it here.
+  exec "$EDITOR_BIN" "$TARGET"
+fi
+
+# Where should it land?
+DEST=""
+case "$MODE" in
+  here) DEST="" ;;
+  free) DEST="$(free_desktop)" ;;
+  ''|*[!0-9]*) DEST="$(free_desktop)" ;;
+  *) DEST="$MODE" ;;
+esac
+
+# Launch detached — the GUI editor must not block the caller.
+"$EDITOR_BIN" "$TARGET" >/dev/null 2>&1 < /dev/null &
+disown 2>/dev/null || true
+
+if [ -z "$DEST" ]; then
+  printf 'ymir-edit[1]{editor,path,desktop}:\n  "%s","%s","current"\n' "$EDITOR_BASE" "$TARGET"
+  exit 0
+fi
+
+# Give the window a moment to map, then move it to its own desktop. The class
+# for VS Code is `code`; for others use the binary's own name.
+case "$EDITOR_BASE" in
+  code|code-insiders|codium) CLASS="code" ;;
+  cursor) CLASS="cursor" ;;
+  zed) CLASS="dev.zed.Zed" ;;
+  subl|sublime_text) CLASS="sublime_text" ;;
+  *) CLASS="$EDITOR_BASE" ;;
+esac
+
+moved=no
+for _ in $(seq 1 20); do
+  sleep 0.25
+  if hyprctl clients -j 2>/dev/null | python3 -c '
+import json,sys
+cls=sys.argv[1]
+try:
+    cs=json.load(sys.stdin)
+except Exception:
+    sys.exit(1)
+sys.exit(0 if any(cls.lower() in (c.get("class") or "").lower() for c in cs) else 1)
+' "$CLASS" 2>/dev/null; then
+    move_window_to "$DEST" "^($CLASS)\$" && moved=yes
+    break
+  fi
+done
+
+printf 'ymir-edit[1]{editor,path,desktop,moved}:\n  "%s","%s","%s","%s"\n' \
+  "$EDITOR_BASE" "$TARGET" "$DEST" "$moved"