Start NestQuest development manually from OpenCode (#150)

Co-authored-by: orchestrator-agent <orchestrator@cubecraftlabs.com>
Co-committed-by: orchestrator-agent <orchestrator@cubecraftlabs.com>

scripts/nq-cycle

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Manually control the durable NestQuest development cycle from OpenCode.
+set -euo pipefail
+
+if [[ $# -ne 1 ]]; then
+  echo "usage: nq-cycle start|stop|status" >&2
+  exit 64
+fi
+
+unit=nestquest-controller.service
+controller=/home/overseer/.local/share/nestquest-controller/scripts/nq-controller
+
+show_status() {
+  systemctl --user show "$unit" -p ActiveState -p SubState -p UnitFileState
+  if [[ -f /home/overseer/.local/state/nestquest-controller/last-run.json ]]; then
+    python3 -c 'import json,pathlib; p=pathlib.Path.home()/".local/state/nestquest-controller/last-run.json"; d=json.loads(p.read_text()); print("LastTickState="+str(d.get("state","unknown"))); print("LastTickTime="+str(d.get("time","unknown")))'
+  fi
+}
+
+case "$1" in
+  start)
+    systemctl --user start "$unit"
+    show_status
+    if session_status=$("$controller" --check-interactive); then
+      echo "$session_status"
+      if [[ "$session_status" == "interactive NestQuest session open" ]]; then
+        echo "Close the interactive NestQuest OpenCode session to let the controller run its first tick."
+      fi
+    else
+      echo "The controller will wait for OpenCode session detection to recover."
+    fi
+    ;;
+  stop)
+    systemctl --user stop "$unit"
+    show_status
+    ;;
+  status)
+    show_status
+    ;;
+  *)
+    echo "usage: nq-cycle start|stop|status" >&2
+    exit 64
+    ;;
+esac