From 75653b7c6e28db4ea87716f4b590af0931f93e22 Mon Sep 17 00:00:00 2001
From: saravanakumardb1 <saravanakumardb1@users.noreply.github.com>
Date: Sat, 30 May 2026 19:25:50 -0700
Subject: [PATCH] feat(aliases): add longrun helper + awake alias for overnight
 agent runs

---
 aliases/README.md         |  8 +++++++-
 aliases/_longrun.alias    | 33 +++++++++++++++++++++++++++++++++
 aliases/_source_all.alias |  1 +
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 aliases/_longrun.alias

diff --git a/aliases/README.md b/aliases/README.md
index 6f4bea4..a600563 100644
--- a/aliases/README.md
+++ b/aliases/README.md
@@ -39,7 +39,7 @@ The loader can be sourced from any directory. It discovers the `aliases/` folder
 ## Requirements
 
 - Supported shells: Bash and Zsh
-- Optional commands used by aliases: `git`, `tmux`, `tree`, and `vim` or `$EDITOR`
+- Optional commands used by aliases: `git`, `tmux`, `tree`, `vim` or `$EDITOR`, and `caffeinate` (macOS, for `awake`/`longrun`)
 
 ## Examples
 
@@ -52,8 +52,14 @@ ta work     # tmux attach-session -t work
 aq <cmd>    # agent-queue runner (init|add|run|status|watch|dash|stop|logs)
 aqs         # agent-queue status
 aqd         # agent-queue Node live dashboard
+awake <cmd> # macOS: run <cmd> while keeping the machine awake (caffeinate -dimsu)
+longrun phase3 codex --full-auto "<prompt>"   # detached+awake+logged overnight run
+ta phase3   # reattach to the run;  tail -f ~/longrun-phase3-*.log  to follow output
 ```
 
+See [`AI.dev/CHEATSHEETS/long-running-jobs.md`](../../learning_ai_common_plat/AI.dev/CHEATSHEETS/long-running-jobs.md)
+(in `learning_ai_common_plat`) for the full overnight-run guide and best practices.
+
 ## Local Aliases
 
 Keep machine- or org-specific shortcuts out of the portable default files. Start from `_local.example.alias` if you want private local aliases such as branch-specific git commands.
diff --git a/aliases/_longrun.alias b/aliases/_longrun.alias
new file mode 100644
index 0000000..19eeea8
--- /dev/null
+++ b/aliases/_longrun.alias
@@ -0,0 +1,33 @@
+# Long-running / overnight agent runs — keep-awake + detachable tmux + logged output.
+# Full guide: AI.dev/CHEATSHEETS/long-running-jobs.md (in learning_ai_common_plat).
+
+# macOS: keep the machine awake while a command runs (prevents sleep stalling the job).
+# On Linux this alias is a no-op label; use `systemd-inhibit` instead.
+alias awake='caffeinate -dimsu'
+
+# longrun <session> <command> [args...]
+#   Runs <command> in a DETACHED tmux session, wrapped in caffeinate (macOS) so the
+#   machine won't sleep, teeing all output to ~/longrun-<session>-<timestamp>.log.
+#   Survives closing the terminal; reattach with `ta <session>`, stop with
+#   `tmux kill-session -t <session>`.
+#   e.g.  longrun phase3 codex --dangerously-bypass-approvals-and-sandbox "Read ... and execute it"
+longrun() {
+  if [ "$#" -lt 2 ]; then
+    echo "usage: longrun <session> <command> [args...]" >&2
+    echo "  e.g. longrun phase3 codex --full-auto \"<the overnight prompt>\"" >&2
+    return 2
+  fi
+  command -v tmux >/dev/null 2>&1 || { echo "longrun: tmux is not installed" >&2; return 1; }
+  local sess="$1"; shift
+  local ts log keep cmd inner
+  ts="$(date +%Y%m%d-%H%M%S)"
+  log="$HOME/longrun-${sess}-${ts}.log"
+  keep=""
+  command -v caffeinate >/dev/null 2>&1 && keep="caffeinate -dimsu "
+  cmd="$(printf '%q ' "$@")"
+  inner="${keep}${cmd}2>&1 | tee \"$log\""
+  tmux new-session -d -s "$sess" "$inner"
+  echo "[longrun] session=$sess"
+  echo "[longrun] log=$log"
+  echo "[longrun] attach: ta $sess   |   tail: tail -f \"$log\"   |   stop: tmux kill-session -t $sess"
+}
diff --git a/aliases/_source_all.alias b/aliases/_source_all.alias
index b6c0edb..619c9dc 100644
--- a/aliases/_source_all.alias
+++ b/aliases/_source_all.alias
@@ -16,3 +16,4 @@ source "$BYTELYST_ALIAS_DIR/_ls.alias"
 source "$BYTELYST_ALIAS_DIR/_general.alias"
 source "$BYTELYST_ALIAS_DIR/_shell.alias"
 source "$BYTELYST_ALIAS_DIR/_agent.alias"
+source "$BYTELYST_ALIAS_DIR/_longrun.alias"