From 1f0bae336c48f8513d24868b8e9a9c769b4f32ef Mon Sep 17 00:00:00 2001
From: Shay <assetoverflow@icloud.com>
Date: Wed, 24 Jun 2026 12:19:53 -0700
Subject: [PATCH] chore(dev): restore tracked agent session launchers (#903)

---
 .goosehints                        |  8 +++
 scripts/setup_codex_environment.sh | 85 ++++++++++++++++++++++++++++++
 scripts/start-codex-session.zsh    | 32 +++++++++++
 scripts/start-grok-session.zsh     | 28 ++++++++++
 4 files changed, 153 insertions(+)
 create mode 100644 .goosehints
 create mode 100755 scripts/setup_codex_environment.sh
 create mode 100755 scripts/start-codex-session.zsh
 create mode 100755 scripts/start-grok-session.zsh

diff --git a/.goosehints b/.goosehints
new file mode 100644
index 00000000..99073ca4
--- /dev/null
+++ b/.goosehints
@@ -0,0 +1,8 @@
+# CORE + builder-II local agent hints
+- temperature 0 everywhere
+- Read AGENTS.md, GROK.md, docs/runtime_contracts.md before edits
+- Proposals are SPECULATIVE until `builder verify` passes
+- Use skills: core-governed-coding, core-verify-loop, core-pre-edit-sweep, core-handoff
+- Slash: /explore /implement /review /verify /handoff /plan
+- Switch model: builder switch-model fast|primary (one model on M1 16GB)
+- versor_condition(F) < 1e-6 — refuse cosine/ANN/HNSW in vault
diff --git a/scripts/setup_codex_environment.sh b/scripts/setup_codex_environment.sh
new file mode 100755
index 00000000..115f34c1
--- /dev/null
+++ b/scripts/setup_codex_environment.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+cd "${CODEX_WORKTREE_PATH:?CODEX_WORKTREE_PATH must name the new worktree}"
+
+echo "== CORE Codex environment setup =="
+echo "Worktree: $CODEX_WORKTREE_PATH"
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "ERROR: CODEX_WORKTREE_PATH is not inside a git worktree."
+  exit 1
+fi
+
+echo
+echo "== Git identity / branch =="
+CURRENT_BRANCH="$(git branch --show-current || true)"
+HEAD_SHA="$(git rev-parse HEAD)"
+echo "Branch: ${CURRENT_BRANCH:-DETACHED}"
+echo "HEAD:   $HEAD_SHA"
+
+echo
+echo "== Fetching remote =="
+git fetch origin --prune
+
+ORIGIN_MAIN_SHA="$(git rev-parse origin/main)"
+MERGE_BASE_SHA="$(git merge-base HEAD origin/main || true)"
+echo "origin/main: $ORIGIN_MAIN_SHA"
+echo "merge-base:  ${MERGE_BASE_SHA:-NONE}"
+
+echo
+echo "== Working tree status =="
+git status --short
+
+: "${CODEX_ALLOW_DIRTY:=0}"
+if [ "$CODEX_ALLOW_DIRTY" != "1" ] && [ -n "$(git status --porcelain)" ]; then
+  echo
+  echo "ERROR: Worktree is dirty before task start."
+  echo "Set CODEX_ALLOW_DIRTY=1 only for an explicit resume or setup-repair task."
+  exit 1
+fi
+
+# Codex creates a detached worktree at the source snapshot selected by the app.
+# Fetching here may move origin/main after that snapshot has been chosen, so Git
+# topology is diagnostic setup evidence rather than an environment precondition.
+if [ "$HEAD_SHA" != "$ORIGIN_MAIN_SHA" ]; then
+  echo
+  if git merge-base --is-ancestor HEAD origin/main; then
+    TOPOLOGY="behind origin/main"
+  elif git merge-base --is-ancestor origin/main HEAD; then
+    TOPOLOGY="ahead of origin/main"
+  else
+    TOPOLOGY="diverged from origin/main"
+  fi
+  echo "WARNING: Worktree HEAD is $TOPOLOGY."
+  echo "Review or reconcile the task base before publishing changes."
+fi
+
+echo
+echo "== Changed files vs origin/main =="
+git diff --name-only origin/main...HEAD || true
+
+echo
+echo "== Toolchain =="
+if ! command -v uv >/dev/null 2>&1; then
+  echo "ERROR: uv is required for AssetOverflow/core."
+  echo "Install it locally first, e.g. brew install uv"
+  exit 1
+fi
+
+if [ -f uv.lock ]; then
+  echo "uv.lock found; syncing with frozen lockfile."
+  uv sync --frozen
+else
+  echo "No uv.lock found; skipping uv sync to avoid generating a lockfile."
+fi
+
+python3 --version || python --version
+uv --version
+
+echo
+echo "== Final status =="
+git status --short
+
+echo
+echo "== Setup complete =="
diff --git a/scripts/start-codex-session.zsh b/scripts/start-codex-session.zsh
new file mode 100755
index 00000000..8ce6c419
--- /dev/null
+++ b/scripts/start-codex-session.zsh
@@ -0,0 +1,32 @@
+#!/usr/bin/env zsh
+set -u
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || return 2 2>/dev/null || exit 2
+
+branch="$(git branch --show-current 2>/dev/null || true)"
+main_sha="$(git rev-parse origin/main 2>/dev/null || true)"
+head_sha="$(git rev-parse HEAD 2>/dev/null || true)"
+
+if [[ -n "${branch}" && "${branch}" != "main" && -z "${CODEX_ALLOW_NON_MAIN_BASE:-}" ]]; then
+  cat <<MSG
+You are on branch '${branch}', not origin/main.
+
+For a new task:
+  git switch main && git pull --ff-only origin main && ./scripts/start-codex-session.zsh
+
+For resuming this PR branch:
+  CODEX_ALLOW_NON_MAIN_BASE=1 ./scripts/start-codex-session.zsh
+
+Current:
+  HEAD        ${head_sha}
+  origin/main ${main_sha}
+MSG
+  return 2 2>/dev/null || exit 2
+fi
+
+if [[ -f scripts/setup_codex_environment.sh ]]; then
+  bash scripts/setup_codex_environment.sh
+fi
+
+source scripts/agent_startup.sh
diff --git a/scripts/start-grok-session.zsh b/scripts/start-grok-session.zsh
new file mode 100755
index 00000000..1744f93a
--- /dev/null
+++ b/scripts/start-grok-session.zsh
@@ -0,0 +1,28 @@
+#!/usr/bin/env zsh
+set -u
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT" || return 2 2>/dev/null || exit 2
+
+branch="$(git branch --show-current 2>/dev/null || true)"
+main_sha="$(git rev-parse origin/main 2>/dev/null || true)"
+head_sha="$(git rev-parse HEAD 2>/dev/null || true)"
+
+if [[ -n "${branch}" && "${branch}" != "main" && -z "${CODEX_ALLOW_NON_MAIN_BASE:-}" ]]; then
+  cat <<MSG
+You are on branch '${branch}', not origin/main.
+
+For a new task:
+  git switch main && git pull --ff-only origin main && ./scripts/start-grok-session.zsh
+
+For resuming this PR branch:
+  CODEX_ALLOW_NON_MAIN_BASE=1 ./scripts/start-grok-session.zsh
+
+Current:
+  HEAD        ${head_sha}
+  origin/main ${main_sha}
+MSG
+  return 2 2>/dev/null || exit 2
+fi
+
+source scripts/agent_startup.sh