@giamme/forge 0.0.0-stage → 0.8.0

package/scripts/forge-solo.sh

@@ -0,0 +1,347 @@
+#!/usr/bin/env bash
+# forge-solo.sh — the single-task forge run: one dwarf implements in the working
+# tree, one QA reviews the diff it actually produced.
+#
+# This exists for the same reason forge-dispatch.sh does. The pipeline is a dozen
+# steps — memory injection, prompt assembly, dispatch, diff capture, review prompt,
+# a second dispatch, two ledger writes — and it used to live in SKILL.md as shell
+# for the orchestrating model to retype on every invocation, from whichever of five
+# harnesses was driving. Several of those steps are silently wrong rather than
+# loudly broken when mistyped: drop ':(exclude).forge' from the capture and forge's
+# own memory goes in front of the reviewer as if the dwarf had written it.
+# Decomposed runs never had this problem because forge-parallel.sh owns the
+# plumbing. Solo runs should not either.
+#
+# What stays with the orchestrator is the judgment: it writes prompt.md, it reads
+# dwarf.last and qa.last, and it reports. Only the plumbing moved.
+#
+# Usage:
+#   forge-solo.sh <run-dir> --repo <dir> --dwarf <spec> [--qa <spec>]
+#                 [--approach <file>] [--yolo-dwarf] [--yolo-qa]
+#                 [--native-review] [--no-memory] [--timeout <s>] [--dry-run] [--ui]
+#                 [--fail-first]
+#
+# Reads  <run-dir>/prompt.md   the implementation instruction (required)
+#        <run-dir>/goal.txt    one line, what the user asked for (optional)
+# Writes <run-dir>/dwarf.{input,last,log,resolved}
+#        <run-dir>/changes.diff
+#        <run-dir>/qa.{input,last,log,resolved}
+#        <run-dir>/verdict      PASS | FAIL | UNKNOWN, when qa emitted one
+#        <run-dir>/failfirst.json  with --fail-first: do the change's tests fail without it?
+#        <run-dir>/status       RUNNING, then this invocation's outcome
+#        <run-dir>/dwarf.spec, qa.spec and attempts.tsv
+#
+# Exit codes: 0 ok | 2 usage | 3 precondition | 4 a dispatch failed
+#             5 the dwarf produced no changes | 7 a dispatch timed out
+#             8 a dispatch hit an infrastructure failure (quota, auth, rate limit, network,
+#               empty output): nothing about the work was judged, fix the cause and re-run
+set -uo pipefail
+
+SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DISPATCH="$SKILL_DIR/scripts/forge-dispatch.sh"
+MEMORY="$SKILL_DIR/scripts/forge-memory.sh"
+source "$SKILL_DIR/scripts/forge-artifact.sh"
+source "$SKILL_DIR/scripts/forge-metrics.sh"
+source "$SKILL_DIR/scripts/forge-fractal-options.sh"
+source "$SKILL_DIR/scripts/forge-ui-options.sh"
+source "$SKILL_DIR/scripts/forge-lib-task.sh"
+JEV_OPTS=0
+[ -f "$SKILL_DIR/scripts/forge-jev-options.sh" ] \
+  && source "$SKILL_DIR/scripts/forge-jev-options.sh" 2>/dev/null && JEV_OPTS=1
+ORIGINAL_ARGS=("$@")
+
+die()  { printf 'forge: %s\n' "$1" >&2; exit "${2:-2}"; }
+note() { printf 'forge: %s\n' "$*" >&2; }
+
+# forge_metric_begin's EXIT trap calls this, before runtime finish and Fractal's
+# _outcome read status. Only this script defines it. It must not change the exit code.
+forge_metric_on_exit() {
+  local rc="${1:-}" status="" word="" cls="" n=0 pick=""
+  [ -n "${RUN:-}" ] || return 0
+  if [ -f "$RUN/verdict" ]; then
+    word=$(awk 'NF { print $1; exit }' "$RUN/verdict" 2>/dev/null || true)
+    case "$word" in
+      PASS|FAIL|UNKNOWN|NOCHANGES|INVALIDATED) status=$word ;;
+    esac
+  fi
+  if [ -z "$status" ]; then
+    case "$rc" in
+      7) status=TIMEOUT ;;
+      8) status=INFRA ;;
+      130|143) status=INTERRUPTED ;;
+      *) status=ERROR ;;
+    esac
+  fi
+  printf '%s\n' "$status" > "$RUN/status" 2>/dev/null || true
+  # The run start cleared both infra files, so any file here is this invocation's.
+  # QA only runs once the dwarf has passed, which makes qa.infra the later stage; no
+  # timestamps are compared (macOS mtimes can tie at whole-second resolution).
+  if [ "$status" = INFRA ]; then
+    for pick in "$RUN/qa.infra" "$RUN/dwarf.infra"; do
+      [ -f "$pick" ] || continue
+      cls=$(awk '/^class=/ { sub(/^class=/, ""); print; exit }' "$pick" 2>/dev/null || true)
+      break
+    done
+  fi
+  n=0
+  if [ -f "$RUN/attempts.tsv" ]; then
+    n=$(grep -c . "$RUN/attempts.tsv" 2>/dev/null) || n=0
+  fi
+  n=$(( ${n:-0} + 1 ))
+  printf '%s\t%s\t%s\t%s\t%s\n' "$(date +%s)" "$n" "$status" "$cls" "${DWARF:-}" >> "$RUN/attempts.tsv" 2>/dev/null || true
+  return 0
+}
+
+if [ "${1:-}" = --help ] || [ "${1:-}" = -h ]; then
+  sed -n '18,33s/^# *//p' "$0"
+  forge_fractal_help
+  echo 'Explicit Fractal retry: repeat the original command with --retry.'
+  exit 0
+fi
+RUN="${1:-}"; [ -n "$RUN" ] || die "usage: forge-solo.sh <run-dir> --repo <dir> --dwarf <spec> [--qa <spec>]"
+case "$RUN" in -*) die "first argument must be the run directory, got '$RUN'" ;; esac
+shift
+
+OUTPUT=summary
+REPO="$PWD"; DWARF=""; QA="opus"; APPROACH=""; YD=""; YQ=""; NATIVE=""; TIMEOUT=""; DRY=0; FAIL_FIRST=0
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --fractal) forge_fractal_flag on || exit $?; shift ;;
+    --fractal-auto-decompose) forge_fractal_flag on || exit $?; FRACTAL_ARGS+=("$1"); shift ;;
+    --no-fractal) forge_fractal_flag off || exit $?; shift ;;
+    --retry) export FORGE_FRACTAL_RETRY=1; shift ;;
+    --fractal-*|--dwarf-low|--dwarf-medium|--dwarf-high) FRACTAL_ARGS+=("$1" "${2:?}"); shift 2 ;;
+    --output) OUTPUT="${2:?}"; shift 2 ;;
+    --repo)       REPO="${2:?--repo needs a value}"; shift 2 ;;
+    --dwarf)      DWARF="${2:?--dwarf needs a spec}"; shift 2 ;;
+    --qa)         QA="${2:?--qa needs a spec}"; shift 2 ;;
+    --approach)   APPROACH="${2:?--approach needs a file}"; shift 2 ;;
+    --yolo-dwarf) YD="--yolo"; shift ;;
+    --yolo-qa)    YQ="--yolo"; shift ;;
+    --native-review) NATIVE="--native-review"; shift ;;
+    --no-ripwire) export FORGE_RIPWIRE=off; shift ;;
+    --no-memory)  export FORGE_MEMORY=off; shift ;;
+    --timeout)    TIMEOUT="${2:?--timeout needs seconds}"; shift 2 ;;
+    --dry-run)    DRY=1; shift ;;
+    --fail-first) FAIL_FIRST=1; shift ;;
+    --ui|--no-ui) forge_ui_flag "$1"; shift ;;
+    *)
+      # `case` is not a loop, so `continue` here belongs to the enclosing while.
+      if [ "$JEV_OPTS" = 1 ]; then
+        forge_jev_flag "$1"; jev_rc=$?
+        case "$jev_rc" in
+          0) shift "$JEV_SHIFT"; continue ;;
+          2) exit 2 ;;
+        esac
+      fi
+      die "unknown option '$1'" ;;
+  esac
+done
+# A solo run has one run dir and no plan, so the selection is frozen there: an
+# explicit retry of the same run dir must not change its mind about Jev.
+[ "$JEV_OPTS" = 1 ] && forge_jev_export
+
+case "$OUTPUT" in summary|full) ;; *) die "--output must be summary or full" ;; esac
+
+# Forge never picks the model: every dispatch spends the user's quota, and choosing
+# for them is not the tool's call.
+[ -n "$DWARF" ] || die "--dwarf is required"
+mkdir -p "$RUN" || die "cannot create run dir '$RUN'"
+[ -s "$RUN/prompt.md" ] || die "no prompt.md in '$RUN' — write the implementation instruction there first"
+[ -d "$REPO" ] || die "--repo '$REPO' is not a directory"
+(cd "$REPO" && git rev-parse --git-dir >/dev/null 2>&1) \
+  || die "'$REPO' is not a git repository — there is no way to capture a diff to review" 3
+
+# The run dir must live outside the working tree: anything forge writes inside the
+# repo turns up in the dwarf's own diff and reaches QA as if the dwarf wrote it.
+case "$(cd "$RUN" && pwd)/" in
+  "$(cd "$REPO" && pwd)"/*) die "run dir '$RUN' is inside the repo; put it somewhere else or it lands in the diff" ;;
+esac
+
+RUN="$(cd "$RUN" && pwd)"
+# Freeze the selection now that the run dir is real and absolute. A retry of this
+# same run dir restores it rather than re-reading whatever flags are passed then.
+[ "$JEV_OPTS" = 1 ] && { forge_jev_restore "$RUN" || true; forge_jev_record "$RUN"; }
+REPO="$(cd "$REPO" && pwd)"
+if [ "$DRY" != 1 ] && [ "${FORGE_SOLO_LOCK:-}" != "$RUN" ]; then
+  exec python3 "$SKILL_DIR/scripts/forge-fractal.py" _lock "$RUN" "$0" "${ORIGINAL_ARGS[@]}"
+fi
+RUN_ID="$(basename "$RUN")"
+export FORGE_CAPABILITY_CACHE="$RUN/capabilities"
+TFLAG=""; [ -n "$TIMEOUT" ] && TFLAG="--timeout $TIMEOUT"
+GOAL="$(head -1 "$RUN/goal.txt" 2>/dev/null || true)"
+
+FFLAGS=()
+[ -z "$YD" ] || FFLAGS+=(--yolo-dwarf)
+[ -z "$YQ" ] || FFLAGS+=(--yolo-qa)
+forge_fractal_select "$RUN" "$REPO" solo "$DRY" --dwarf "$DWARF" --qa "$QA" ${FFLAGS[@]+"${FFLAGS[@]}"} || exit $?
+if [ -n "${FORGE_FRACTAL_RUN:-}" ]; then
+  # The UI choice is per invocation: a tmux resume replays these args and must not open it again.
+  REMEMBER_ARGS=()
+  for arg in "${ORIGINAL_ARGS[@]}"; do
+    case "$arg" in --ui|--no-ui) ;; *) REMEMBER_ARGS+=("$arg") ;; esac
+  done
+  python3 "$SKILL_DIR/scripts/forge-fractal.py" _remember "$0" ${REMEMBER_ARGS[@]+"${REMEMBER_ARGS[@]}"} || exit $?
+fi
+if [ -n "${FORGE_FRACTAL_RUN:-}" ] && [ "$DRY" != 1 ] && [ "${FORGE_FRACTAL_RETRY:-}" != 1 ]; then
+  python3 "$SKILL_DIR/scripts/forge-fractal.py" _checkpoint "$REPO"
+  checkpoint_rc=$?
+  [ "$checkpoint_rc" != 0 ] || exit 0
+  [ "$checkpoint_rc" = 1 ] || exit "$checkpoint_rc"
+fi
+
+# The dispatches see a review snapshot, not the repo, so the run dir names it for the dataset.
+[ "$DRY" = 1 ] || printf '%s\n' "$REPO" > "$RUN/repo"
+# Every real run, --ui or not: forge-ui's view of this repo's runs reads the registry.
+[ "$DRY" = 1 ] || forge_ui_register "$RUN"
+# Recorded before any dispatch: forge-ui opens this dir immediately, and a re-run
+# that dies early must not keep showing the previous invocation's verdict.
+if [ "$DRY" != 1 ]; then
+  forge_metric_begin "$RUN" solo
+  printf '%s\n' RUNNING > "$RUN/status"
+  printf '%s\n' "$DWARF" > "$RUN/dwarf.spec"
+  printf '%s\n' "$QA" > "$RUN/qa.spec"
+  rm -f "$RUN/verdict" "$RUN/dwarf.infra" "$RUN/qa.infra"
+fi
+
+# --- dwarf --------------------------------------------------------------------
+/bin/bash "$MEMORY" inject "$REPO" dwarf --run-dir "$RUN" > "$RUN/dwarf.memory"
+python3 "$SKILL_DIR/scripts/forge-prompt.py" --requirements "$RUN/prompt.md" --approach "$APPROACH" --memory "$RUN/dwarf.memory" > "$RUN/context.md" || exit 3
+{
+  cat "$RUN/context.md"
+  cat <<'EOF'
+
+Edit the files in this repository directly. When you are done, run whatever tests
+or checks the project already has and report the result.
+
+You are running headless: nobody is at the other end and no one can answer a
+question. If something is ambiguous, pick the most reasonable interpretation,
+proceed, and state the assumption in your final message.
+EOF
+  echo; python3 "$SKILL_DIR/scripts/forge-contract.py" dwarf
+  echo; /bin/bash "$MEMORY" note dwarf
+} > "$RUN/dwarf.input"
+
+if [ "$DRY" = 1 ]; then
+  echo "--- dry run ---"
+  [ "$FORGE_UI_WANTED" != 1 ] || note "--ui ignored: a dry run starts no UI"
+  /bin/bash "$DISPATCH" dwarf "$DWARF" --repo "$REPO" --run-dir "$RUN" \
+    --ripwire-query-file "$RUN/prompt.md" --prompt-file "$RUN/dwarf.input" $YD $TFLAG --dry-run
+  echo
+  echo "qa would be: $QA $NATIVE $YQ"
+  echo "dwarf prompt: $RUN/dwarf.input ($(wc -l < "$RUN/dwarf.input" | tr -d ' ') lines)"
+  exit 0
+fi
+
+forge_metric_phase preflight
+/bin/bash "$DISPATCH" doctor --spec "$DWARF" --role dwarf $YD $TFLAG || exit $?
+/bin/bash "$DISPATCH" doctor --spec "$QA" --role qa $YQ $NATIVE $TFLAG || exit $?
+/bin/bash "$SKILL_DIR/scripts/forge-install-ripwire.sh" || true
+# After the _lock re-exec and the Fractal checkpoint exit, so it runs once per run.
+forge_ui_launch "$RUN"
+forge_metric_phase snapshot
+if [ -n "${FORGE_FRACTAL_RUN:-}" ] && [ -s "$RUN/start.tree" ]; then
+  START="$(cat "$RUN/start.tree")"
+else
+  START="$(forge_tree "$REPO")" || die "cannot record starting snapshot" 3
+fi
+echo "$START" > "$RUN/start.tree"
+git -C "$REPO" diff --binary HEAD "$START" -- . ':(exclude).forge' > "$RUN/existing.diff"
+forge_metric_phase dispatch
+note "dwarf $DWARF in $REPO"
+guard_before_dwarf "$REPO" "$RUN"
+/bin/bash "$DISPATCH" dwarf "$DWARF" --repo "$REPO" --run-dir "$RUN" \
+  --ripwire-query-file "$RUN/prompt.md" --prompt-file "$RUN/dwarf.input" $YD $TFLAG --output "$OUTPUT"
+rc=$?
+dur_dwarf="$(sed -n 's/^duration_s=//p' "$RUN/dwarf.resolved" 2>/dev/null | tail -1)"
+/bin/bash "$MEMORY" record "$REPO" --last "$RUN/dwarf.last" --role dwarf \
+  --run-id "$RUN_ID" --model "$DWARF" --run-dir "$RUN" \
+  --duration "${dur_dwarf:--}" >/dev/null 2>&1
+[ "$rc" = 7 ] && die "the dwarf exceeded its timeout — see $RUN/dwarf.log" 7
+[ "$rc" = 8 ] && die "the dwarf hit an infrastructure failure ($(sed -n 's/^class=//p' "$RUN/dwarf.infra" 2>/dev/null | head -1)) — nothing was reviewed; fix the cause and run again (see $RUN/dwarf.infra)" 8
+[ "$rc" -ne 0 ] && die "the dwarf dispatch failed — see $RUN/dwarf.log" 4
+guard_after_dwarf "$REPO" "$RUN" solo
+
+forge_metric_phase snapshot
+# --- the real diff ------------------------------------------------------------
+# Diff complete filesystem snapshots; the private index preserves user staging.
+END="$(forge_tree "$REPO")" || die "cannot capture implementation" 3
+echo "$END" > "$RUN/reviewed.tree"
+git -C "$REPO" diff --binary "$START" "$END" -- . ':(exclude).forge' > "$RUN/changes.diff" || die "cannot create diff" 3
+
+if [ ! -s "$RUN/changes.diff" ]; then
+  # An exit-0 harness with an empty final message and no changes never really ran.
+  grep -qx 'class=empty' "$RUN/dwarf.infra" 2>/dev/null && die "the dwarf returned nothing (empty output, no changes) — an infrastructure failure, not a refusal; fix the cause and run again (see $RUN/dwarf.infra)" 8
+  note "the dwarf produced no changes at all — see $RUN/dwarf.last for what it said"
+  echo NOCHANGES > "$RUN/verdict"
+  exit 5
+fi
+
+REVIEW="$RUN/review-$(date +%s)-$$"
+forge_review_snapshot "$REPO" "$START" "$END" "$REVIEW" || die "cannot create review snapshot" 3
+SOURCE_FP="$(forge_fingerprint "$REPO")" || exit 3
+[ "$(forge_tree "$REPO")" = "$END" ] || { echo INVALIDATED > "$RUN/verdict"; die "source changed while preparing QA" 5; }
+REVIEW_FP="$(forge_fingerprint "$REVIEW")" || exit 3
+printf '%s\n' "$SOURCE_FP" > "$RUN/source.fingerprint"
+printf '%s\n' "$REVIEW_FP" > "$RUN/review.fingerprint"
+forge_metric_phase preparation
+# --- qa -----------------------------------------------------------------------
+rm -f "$RUN/failfirst.json" "$RUN/failfirst.txt"
+if [ "$FAIL_FIRST" = 1 ]; then
+  # Opt-in and advisory: the reviewer reads the evidence; nothing here changes a verdict.
+  forge_fail_first "$REVIEW" "$RUN" "$REPO"
+  note "fail-first evidence for the reviewer: $RUN/failfirst.json"
+fi
+/bin/bash "$MEMORY" inject "$REPO" qa --run-dir "$RUN" > "$RUN/qa.memory"
+{
+  python3 "$SKILL_DIR/scripts/forge-prompt.py" --requirements "$RUN/prompt.md" --approach "$APPROACH" --goal "$RUN/goal.txt" --memory "$RUN/dwarf.memory" --memory "$RUN/qa.memory"
+  python3 "$SKILL_DIR/scripts/forge-contract.py" qa --part head --kind solo
+  echo
+  if [ -s "$RUN/failfirst.txt" ]; then cat "$RUN/failfirst.txt"; echo; fi
+  python3 "$SKILL_DIR/scripts/forge-contract.py" qa --part tail --kind solo
+  echo
+  echo '```diff'; cat "$RUN/changes.diff"; echo '```'
+  echo; /bin/bash "$MEMORY" note qa
+  echo "Place any learning notes before the final FORGE_VERDICT: PASS or FORGE_VERDICT: FAIL line."
+} > "$RUN/qa.input"
+
+forge_metric_phase dispatch
+note "qa $QA on $(wc -l < "$RUN/changes.diff" | tr -d ' ') diff lines"
+/bin/bash "$DISPATCH" qa "$QA" --repo "$REVIEW" --review-base "$(cat "$RUN/review.base")" --run-dir "$RUN" \
+  --ripwire-query-file "$RUN/prompt.md" --prompt-file "$RUN/qa.input" $YQ $NATIVE $TFLAG --output "$OUTPUT"
+rc=$?
+forge_metric_phase verification
+verdict="$(forge_verdict "$RUN/qa.last")"
+[ -n "$NATIVE" ] && verdict=UNKNOWN
+if [ "$(forge_fingerprint "$REPO")" != "$SOURCE_FP" ] || [ "$(forge_fingerprint "$REVIEW")" != "$REVIEW_FP" ]; then
+  echo INVALIDATED > "$RUN/verdict"
+  die "source or review artifact changed during QA; review invalidated" 5
+fi
+dur_qa="$(sed -n 's/^duration_s=//p' "$RUN/qa.resolved" 2>/dev/null | tail -1)"
+/bin/bash "$MEMORY" record "$REPO" --last "$RUN/qa.last" --role qa \
+  --run-id "$RUN_ID" --model "$QA" --verdict "${verdict:-UNKNOWN}" --run-dir "$RUN" \
+  --duration "${dur_qa:--}" >/dev/null 2>&1
+[ "$rc" = 7 ] && die "qa exceeded its timeout — the dwarf's changes are still in the tree; see $RUN/qa.log" 7
+[ "$rc" = 8 ] && die "qa hit an infrastructure failure ($(sed -n 's/^class=//p' "$RUN/qa.infra" 2>/dev/null | head -1)) — the dwarf's changes are still in the tree and unreviewed; fix the cause and review again (see $RUN/qa.infra)" 8
+[ "$rc" -ne 0 ] && die "the qa dispatch failed — the dwarf's changes are still in the tree; see $RUN/qa.log" 4
+
+# --native-review is codex's own reviewer, which refuses a custom prompt alongside
+# its scope flags — so it never sees the verdict instruction and cannot emit one.
+echo "${verdict:-UNKNOWN}" > "$RUN/verdict"
+
+echo
+echo "dwarf:  $DWARF   ${dur_dwarf:-?}s"
+echo "qa:     $QA   ${dur_qa:-?}s   verdict: ${verdict:-UNKNOWN}"
+echo "diff:   $RUN/changes.diff"
+echo "read:   $RUN/dwarf.last and $RUN/qa.last"
+echo
+if grep -q '^self-commit' "$RUN/guard.txt" 2>/dev/null; then
+  echo "The dwarf COMMITTED in $REPO although it was told not to. The review above covers its"
+  echo "changes either way. To turn its commit(s) back into uncommitted changes:"
+  echo "  git -C $REPO reset --soft $(cat "$RUN/dwarf.head.before" 2>/dev/null)"
+  echo "Forge itself committed, pushed and reset nothing."
+else
+  echo "The changes are UNCOMMITTED in $REPO. Nothing was committed, pushed or reset."
+fi
+[ ! -s "$RUN/guard.txt" ] || { echo; echo "implementer guard notes:"; sed 's/^/  /' "$RUN/guard.txt"; }
+forge_update_notice

package/scripts/forge-ui-options.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# Source in runners (forge-solo.sh, forge-parallel.sh plan and run). Compatible with macOS Bash 3.2.
+#
+# forge-ui is opt-in per run: the orchestrator asks the user and passes the answer as
+# --ui. The flag is never persisted, and launching never decides whether the run goes on.
+# Registering a run (forge_ui_register) is not part of that choice: it happens on every
+# run, so forge-ui can later show all of a repo's runs, including those never opened in it.
+FORGE_UI_WANTED=0
+
+# forge_ui_flag ARG — returns 0 and records the choice for --ui / --no-ui, 1 for anything else.
+forge_ui_flag() {
+  case "${1:-}" in
+    --ui)    FORGE_UI_WANTED=1 ;;
+    --no-ui) FORGE_UI_WANTED=0 ;;
+    *)       return 1 ;;
+  esac
+}
+
+# forge_ui_launch DIR — open DIR in the shared forge-ui server when --ui was given.
+# Always returns 0: a UI that cannot start must not change the run's exit code. The
+# launcher's stdin is /dev/null so it can never wait for a terminal.
+forge_ui_launch() {
+  [ "${FORGE_UI_WANTED:-0}" = 1 ] || return 0
+  if [ "${FORGE_UI:-}" = off ]; then
+    printf 'forge: FORGE_UI=off; not starting forge-ui\n' >&2
+    return 0
+  fi
+  python3 "$SKILL_DIR/scripts/forge-ui.py" open "$1" </dev/null \
+    || printf 'forge: forge-ui did not start; the run goes on (later: %s/forge ui open %s)\n' "$SKILL_DIR" "$1" >&2
+  return 0
+}
+
+# forge_ui_register DIR — note DIR in forge's run registry ($XDG_CONFIG_HOME/forge/runs),
+# under the repo named in DIR/repo. Called on every run, whatever --ui and FORGE_UI say,
+# because forge-ui's view of a repo's runs reads that registry. Always returns 0 and prints
+# nothing: the registry can be unwritable or the repo file odd, and neither may change a
+# run's output or exit code. -I keeps a PYTHON* variable or a stray module in the current
+# directory from changing what runs. FORGE_RUN_REGISTRY=off turns it off.
+forge_ui_register() {
+  python3 -I "$SKILL_DIR/scripts/forge_registry.py" register "$1" </dev/null >/dev/null 2>&1 || true
+  return 0
+}