@askexenow/exe-os 0.8.0

package/src/commands/exe/employee-heartbeat.md

@@ -0,0 +1,44 @@
+---
+description: Check task folder for open tasks and output directly if found
+allowed-tools: Bash
+---
+
+# Employee Heartbeat — Task Check
+
+This command is designed for `/loop`. It scans the employee's task folder and outputs task info directly when open tasks exist.
+
+```bash
+# Detect agent from EXE_SESSION_NAME env var or tmux session name
+SESSION_KEY="${EXE_SESSION_NAME:-$(tmux display-message -p '#{session_name}' 2>/dev/null)}"
+if [ -n "$SESSION_KEY" ]; then
+  AGENT=$(echo "$SESSION_KEY" | sed -E 's/-exe[0-9]+$//; s/[0-9]+$//')
+else
+  AGENT="UNKNOWN"
+fi
+
+# Skip if no agent or exe/default
+if [ "$AGENT" = "UNKNOWN" ] || [ "$AGENT" = "exe" ] || [ "$AGENT" = "default" ]; then
+  exit 0
+fi
+
+# Idle detection: stay silent if agent had activity within last 120 seconds
+ACTIVITY_FILE="${HOME}/.exe-os/session-cache/last-activity-${SESSION_KEY}.json"
+if [ -f "$ACTIVITY_FILE" ]; then
+  IDLE_CHECK=$(SESSION_KEY="$SESSION_KEY" node -e "
+    try {
+      const a = JSON.parse(require('fs').readFileSync(process.env.HOME+'/.exe-os/session-cache/last-activity-'+process.env.SESSION_KEY+'.json','utf8'));
+      const diff = Date.now() - a.timestamp;
+      console.log(diff < 120000 ? 'busy' : 'idle');
+    } catch { console.log('idle'); }
+  " 2>/dev/null)
+  if [ "$IDLE_CHECK" = "busy" ]; then
+    exit 0
+  fi
+fi
+
+# Use canonical scanner — single source of truth for task status detection
+node "$(npm root -g)/exe-os/dist/bin/scan-tasks.js" "exe/$AGENT" --format=mandatory 2>/dev/null
+```
+
+**If the script outputs task info:** read the task file and begin working immediately. Do not ask what to do.
+**If the script outputs nothing:** no tasks — stay silent.

package/src/commands/exe/forget.md

@@ -0,0 +1,15 @@
+---
+description: Delete memories by ID, agent, or search query
+allowed-tools: Bash
+---
+
+Delete memories from the local database. Requires confirmation before deletion.
+
+Usage:
+- `/exe-forget --id <memory-id>` — delete a single memory by ID
+- `/exe-forget --agent <name>` — delete all memories for an employee
+- `/exe-forget --query "<search>"` — delete memories matching a search query
+
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-forget.js" "$ARGUMENTS"
+```

package/src/commands/exe/heartbeat.md

@@ -0,0 +1,92 @@
+---
+description: Proactive check — scan for notifications, stale tasks, and error spikes
+allowed-tools: Bash, Read, Glob, recall_my_memory, ask_team_memory
+---
+
+# Heartbeat — Proactive Status Check
+
+You are exe running a background heartbeat. Be SILENT unless something needs attention. Do NOT output anything if everything is fine.
+
+## Check 1: Unread notifications
+
+```bash
+node -e "
+const fs = require('fs');
+const dir = require('os').homedir() + '/.exe-os/notifications/';
+try {
+  const files = fs.readdirSync(dir).filter(f => f.endsWith('.json'));
+  const unread = files.map(f => {
+    try { return JSON.parse(fs.readFileSync(dir + f, 'utf8')); } catch { return null; }
+  }).filter(n => n && !n.read);
+  if (unread.length > 0) {
+    console.log('UNREAD:' + JSON.stringify(unread));
+    // Mark as read so they don't repeat on next heartbeat
+    files.forEach(f => {
+      try {
+        const full = dir + f;
+        const n = JSON.parse(fs.readFileSync(full, 'utf8'));
+        if (!n.read) { n.read = true; fs.writeFileSync(full, JSON.stringify(n, null, 2)); }
+      } catch {}
+    });
+  } else {
+    console.log('HEARTBEAT_OK_NOTIFICATIONS');
+  }
+} catch { console.log('HEARTBEAT_OK_NOTIFICATIONS'); }
+"
+```
+
+## Check 2: Stale tasks (open > 24h)
+
+```bash
+node -e "
+const fs = require('fs');
+const glob = require('path');
+const home = require('os').homedir();
+const dir = home + '/.exe-os/';
+// Check task files across known project directories
+try {
+  const { createClient } = require('@libsql/client');
+  const key = fs.readFileSync(dir + 'master.key', 'utf8').trim();
+  const client = createClient({ url: 'file:' + dir + 'memories.db', encryptionKey: key });
+  client.execute(\"SELECT id, title, assigned_to, project_name, created_at FROM tasks WHERE status = 'open'\").then(r => {
+    const now = Date.now();
+    const stale = r.rows.filter(row => (now - new Date(String(row.created_at)).getTime()) > 86400000);
+    if (stale.length > 0) {
+      console.log('STALE:' + JSON.stringify(stale.map(s => ({ title: s.title, assignee: s.assigned_to, project: s.project_name, age_hours: Math.round((now - new Date(String(s.created_at)).getTime()) / 3600000) }))));
+    } else {
+      console.log('HEARTBEAT_OK_TASKS');
+    }
+  }).catch(() => console.log('HEARTBEAT_OK_TASKS'));
+} catch { console.log('HEARTBEAT_OK_TASKS'); }
+"
+```
+
+## Check 3: Recent error spikes
+
+```bash
+ls -t ~/.exe-os/notifications/*error_spike* 2>/dev/null | head -5 | while read f; do
+  age=$((( $(date +%s) - $(stat -f %m "$f") )))
+  if [ "$age" -lt 3600 ]; then
+    cat "$f"
+  fi
+done || echo "HEARTBEAT_OK_ERRORS"
+```
+
+## Evaluate results
+
+After running all three checks:
+
+- If ALL checks returned `HEARTBEAT_OK_*` — output NOTHING. Stay completely silent. The user doesn't need to know you checked.
+- If ANY check found something, output a brief summary. Format:
+
+```
+--- exe heartbeat ---
+[what needs attention — keep it to 1-3 lines]
+```
+
+Examples:
+- `yoshi completed 2 tasks in exe-os`
+- `3 stale tasks: "fix auth" (yoshi, 36h), "brand update" (mari, 28h), "deploy fix" (yoshi, 25h)`
+- `error spike: yoshi hit 18 errors in exe-create (45m ago)`
+
+Do NOT explain what the heartbeat is. Do NOT say "everything is fine." If nothing needs attention, produce zero output.

package/src/commands/exe/intercom.md

@@ -0,0 +1,81 @@
+---
+description: Receive dispatched task via tmux send-keys and begin working
+allowed-tools: Bash
+---
+
+# Intercom — Task Dispatch Receiver
+
+Triggered by exe via `tmux send-keys -t {window} '/exe-intercom' Enter`. Scans the employee's task folder and starts working immediately if tasks exist.
+
+```bash
+# Detect agent from EXE_SESSION_NAME env var or tmux session name
+if [ -n "$EXE_SESSION_NAME" ]; then
+  AGENT=$(echo "$EXE_SESSION_NAME" | sed -E 's/-exe[0-9]+$//; s/[0-9]+$//')
+elif [ -n "$TMUX" ]; then
+  AGENT=$(tmux display-message -p '#{session_name}' 2>/dev/null | sed -E 's/-exe[0-9]+$//; s/[0-9]+$//')
+else
+  AGENT="UNKNOWN"
+fi
+
+# Skip if no agent
+if [ "$AGENT" = "UNKNOWN" ] || [ "$AGENT" = "default" ]; then
+  exit 0
+fi
+
+# Exe gets review notifications instead of task dispatch
+if [ "$AGENT" = "exe" ]; then
+  node "$(npm root -g)/exe-os/dist/bin/exe-pending-reviews.js" 2>/dev/null
+  # Exe also subscribes to notifications (subtasks_complete, task_complete, etc.)
+  # so parent-of-parent rollups surface live instead of only at boot.
+  node "$(npm root -g)/exe-os/dist/bin/exe-pending-notifications.js" "$AGENT" 2>/dev/null
+  exit 0
+fi
+
+# Use canonical scanner — single source of truth for task status detection
+node "$(npm root -g)/exe-os/dist/bin/scan-tasks.js" "exe/$AGENT" --format=mandatory 2>/dev/null
+
+# Check for pending messages
+node "$(npm root -g)/exe-os/dist/bin/exe-pending-messages.js" "$AGENT" 2>/dev/null
+
+# Check for pending notifications (subtasks_complete, rollup signals, etc.)
+# Employees acting as parent-of-parents (e.g. yoshi holding multiple parent
+# tasks) need these too — not only exe. See the parent-cascade audit §6.
+node "$(npm root -g)/exe-os/dist/bin/exe-pending-notifications.js" "$AGENT" 2>/dev/null
+```
+
+### For exe (AGENT=exe)
+**If output shows `[REVIEW NOTIFICATIONS]` and you are idle (no active conversation):** start reviewing immediately. Run `/exe-review`. Do not ask the founder for permission.
+**If output shows `[REVIEW NOTIFICATIONS]` and the founder is mid-conversation:** note them briefly and continue. Review after the current topic concludes.
+**If output is empty:** no pending reviews — stay silent.
+
+### For employees (all other agents)
+**If output starts with "MANDATORY:"** — you are idle. Read the task file and begin working immediately. Do not ask what to do.
+**If output starts with "Continue working on:"** — you are already busy. Finish your current task first. Task chaining will pick up the next task automatically.
+**If output is empty:** no tasks — stay silent.
+
+---
+
+## Context-full intercom format
+
+When an employee's context window fills, they send this intercom to exe before stopping:
+
+```
+/exe-intercom context-full: <name> hit capacity. Checkpoint saved. Resume task <task-id>.
+```
+
+**What exe does when it receives this:**
+1. **Verify before killing.** Call `verifyPaneAtCapacity(sessionName)` from `src/lib/tmux-routing.ts`. It captures the last 200 lines of the employee's pane and runs the filtered capacity matcher.
+   - If `atCapacity: false`: the intercom is a false positive (pane echo, rendered skill doc, RESUME banner matching the intercom syntax). Do NOT kill. Send a nudge via `tmux send-keys`: `"False context-full detected (reason: <result.reason>). Continue working. If intentional, explain trigger."` Report to founder and stop.
+   - If `atCapacity: true`: proceed to step 2.
+2. Kill the employee's session: `tmux kill-session -t <name>-<exe-session>`
+3. Create a resume task via `create_task` (auto-dispatches a fresh session)
+4. Report to founder
+
+**What the employee does before sending this:**
+1. `store_memory` with text starting `"CONTEXT CHECKPOINT [<task-id>]: ..."` — captures current state
+2. Send the context-full intercom to exe
+3. Stop — do not continue working
+
+**What the resumed session does on boot:**
+1. `recall_my_memory("CONTEXT CHECKPOINT [<task-id>]")` — retrieves exact state
+2. Continues from where the previous session stopped

package/src/commands/exe/kill.md

@@ -0,0 +1,34 @@
+---
+description: Stop an employee's tmux session
+allowed-tools: Bash
+argument-hint: [employee-name]
+---
+
+Kill the tmux session for the named employee.
+
+Delegates to `exe-kill` so the manual kill is recorded in `session_kills`
+telemetry (SL-4 Phase 1) before tmux tears the session down. Falls back to
+the raw tmux path when `exe-kill` is not on PATH (older installs).
+
+Run:
+```bash
+NAME="$ARGUMENTS"
+if command -v exe-kill >/dev/null 2>&1; then
+  exe-kill "${NAME}"
+else
+  EXE_SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null)
+  TARGET="${NAME}-${EXE_SESSION}"
+  if tmux has-session -t "${TARGET}" 2>/dev/null; then
+    tmux kill-session -t "${TARGET}"
+    echo "Session '${TARGET}' killed."
+  elif tmux list-sessions -F '#{session_name}' 2>/dev/null | grep -q "^${NAME}-"; then
+    MATCH=$(tmux list-sessions -F '#{session_name}' 2>/dev/null | grep "^${NAME}-" | head -1)
+    tmux kill-session -t "${MATCH}"
+    echo "Session '${MATCH}' killed."
+  else
+    echo "No active session found for '${NAME}'."
+  fi
+fi
+```
+
+Report the result to the user.

package/src/commands/exe/launch.md

@@ -0,0 +1,52 @@
+---
+description: Spawn employee sessions in tmux for parallel autonomous work
+allowed-tools: Bash
+argument-hint: [employee names...]
+---
+
+Launch one or more employees as detached tmux sessions. Each session uses `ensureEmployee()` — checks if alive first, spawns if not.
+
+**Prerequisites:** Must be inside a tmux session. Claude Code CLI must be in PATH.
+
+1. First, verify we're inside tmux:
+```bash
+# Robust tmux detection — handles su/sudo login shells (env vars stripped)
+([ -n "$TMUX" ] || [ -n "$TMUX_PANE" ] || [[ "$TERM" == tmux* ]] || [[ "$TERM" == screen* ]] || tmux display-message -p '#{session_name}' >/dev/null 2>&1) && echo "TMUX_OK" || echo "TMUX_MISSING"
+```
+
+If TMUX_MISSING, tell the user:
+```
+tmux is required. Start a tmux session first:
+  tmux new-session -s work
+  claude
+  /exe
+```
+
+2. Load the employee roster and validate all names from $ARGUMENTS:
+```bash
+cat ~/.exe-os/exe-employees.json 2>/dev/null || echo "NO_ROSTER"
+```
+
+For each name in $ARGUMENTS, verify it exists in the roster. If any name is not found, report it and skip that name.
+
+3. For each validated employee name, ensure they're running via `ensureEmployee()`:
+```bash
+NAME="<employee>"
+EXE_SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null)
+RESULT=$(node -e "const {ensureEmployee}=require('$(npm root -g)/exe-os/dist/lib/tmux-routing.js'); const r=ensureEmployee('${NAME}','${EXE_SESSION}','$(pwd)'); console.log(JSON.stringify(r));")
+echo "${NAME}: ${RESULT}"
+```
+
+4. After all sessions are spawned, show a summary:
+
+```
+## Launched Sessions
+
+| Employee | Session | Log |
+|----------|---------|-----|
+| bob | bob-exe1 | ~/.exe-os/session-logs/bob-1234567890.log |
+| tom | tom-exe1 | ~/.exe-os/session-logs/tom-1234567890.log |
+
+Use `/exe-sessions` to monitor, `/exe-logs <name>` to tail output, `/exe-kill <name>` to stop.
+Switch sessions: Ctrl-b s (session picker)
+```

package/src/commands/exe/link.md

@@ -0,0 +1,17 @@
+---
+description: Link another device by exporting or importing your encryption key
+allowed-tools: Bash
+argument-hint: [export|import]
+---
+
+**Deprecated:** Use `/exe-cloud` instead — it handles key import AND cloud sync in one step.
+
+- `/exe-cloud` — full setup (key + cloud)
+- `/exe-cloud sync` — export everything for a new device
+- `/exe-cloud status` — check sync status
+
+Legacy command still works:
+
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-link.js" $ARGUMENTS
+```

package/src/commands/exe/logs.md

@@ -0,0 +1,22 @@
+---
+description: Tail recent output from an employee's session log
+allowed-tools: Bash
+argument-hint: [employee-name]
+---
+
+Show the last 50 lines from the most recent session log for the named employee.
+
+Run:
+```bash
+NAME="$ARGUMENTS"
+LOG=$(ls -t ~/.exe-os/session-logs/${NAME}-*.log 2>/dev/null | head -1)
+if [ -n "$LOG" ]; then
+  echo "Log: $LOG"
+  echo "---"
+  tail -50 "$LOG"
+else
+  echo "No session logs found for ${NAME}. Has the employee been launched with /exe-launch?"
+fi
+```
+
+Show the output to the user. If the log is empty or the employee hasn't been launched, say so.

package/src/commands/exe/new-employee.md

@@ -0,0 +1,12 @@
+---
+description: Create a new employee with optional template (yoshi, mari, gen)
+allowed-tools: Bash
+argument-hint: <name> [--template <template>]
+---
+
+Create a new named employee for the exe-os system.
+
+Run this command:
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-new-employee.js" $ARGUMENTS
+```

package/src/commands/exe/review.md

@@ -0,0 +1,14 @@
+---
+description: Review a specialist's most recent session and verify completions
+allowed-tools: Bash
+argument-hint: <employee-name>
+---
+
+After a specialist session ends, run this to have exe review the session.
+Exe will analyze the specialist's recent work, verify completions, and
+update organizational memory with the outcomes.
+
+Run this command:
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-review.js" $ARGUMENTS
+```

package/src/commands/exe/schedule.md

@@ -0,0 +1,108 @@
+---
+description: Create, list, or delete scheduled recurring jobs
+allowed-tools: Bash, Read, CronCreate, CronDelete
+argument-hint: "<time> <description>" | list | delete <id>
+---
+
+Manage time-based recurring jobs. Schedules persist in the DB and are re-registered on boot.
+
+## Parse $ARGUMENTS
+
+Determine the action:
+
+- `list` → show all active schedules
+- `delete <id>` → remove a schedule
+- `run <id>` → execute a schedule's prompt immediately
+- `"<time>" "<description>"` → create a new schedule
+
+---
+
+## Action: list
+
+```bash
+node -e "
+  const {initStore}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/store.js'));
+  const {listSchedules}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/schedules.js'));
+  (async()=>{
+    await initStore();
+    const schedules=await listSchedules();
+    if(schedules.length===0){console.log('No active schedules.');return;}
+    console.log('ID       | Cron             | Type    | Description');
+    console.log('---------|------------------|---------|------------------');
+    for(const s of schedules){
+      console.log(s.id.padEnd(9)+'| '+s.cron.padEnd(17)+'| '+s.jobType.padEnd(8)+'| '+s.description);
+    }
+  })().catch(e=>console.error(e.message))
+" 2>/dev/null
+```
+
+Print the output as-is.
+
+---
+
+## Action: delete <id>
+
+```bash
+ID="<extracted-id>"
+node -e "
+  const {initStore}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/store.js'));
+  const {deleteSchedule}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/schedules.js'));
+  (async()=>{
+    await initStore();
+    const ok=await deleteSchedule('${ID}');
+    console.log(ok?'Schedule ${ID} deleted.':'Schedule ${ID} not found.');
+  })().catch(e=>console.error(e.message))
+" 2>/dev/null
+```
+
+---
+
+## Action: create
+
+1. Parse the time expression from $ARGUMENTS. The first quoted string or recognizable time expression is the schedule, the rest is the description.
+
+2. Convert to cron using the built-in parser:
+
+```bash
+TIME_EXPR="<extracted-time>"
+node -e "
+  const {parseHumanCron}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/schedules.js'));
+  console.log(parseHumanCron('${TIME_EXPR}'))
+" 2>/dev/null
+```
+
+3. Determine job type:
+   - If description mentions "test", "build", "deploy" → type: "work", assigned_to: "yoshi"
+   - If description mentions "report", "summary", "status" → type: "report"
+   - If description mentions "sync", "backfill", "clean" → type: "maintenance"
+   - Default: "report"
+
+4. Ask the user: "Should this job survive session restarts? (Uses system crontab)"
+   - If yes: `use_crontab = true`
+   - If no: `use_crontab = false` (re-registered on boot via CronCreate)
+
+5. Create the schedule:
+
+```bash
+CRON="<cron-expression>"
+DESC="<description>"
+TYPE="<job-type>"
+CRONTAB="<0-or-1>"
+node -e "
+  const {initStore}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/store.js'));
+  const {createSchedule}=require(require('path').join(require('child_process').execSync('npm root -g',{encoding:'utf8'}).trim(),'exe-os/dist/lib/schedules.js'));
+  (async()=>{
+    await initStore();
+    const s=await createSchedule({cron:'${CRON}',description:'${DESC}',jobType:'${TYPE}',useCrontab:${CRONTAB}===1});
+    console.log('Schedule created: '+s.id);
+    console.log('Cron: '+s.cron);
+    console.log('Type: '+s.jobType);
+    console.log('Crontab: '+(s.useCrontab?'yes (survives restarts)':'no (session-scoped, re-registered on boot)'));
+  })().catch(e=>console.error(e.message))
+" 2>/dev/null
+```
+
+6. If not using crontab, register with CronCreate now:
+   - Use CronCreate with the cron expression and the description as the prompt
+
+Report the result to the user.

package/src/commands/exe/search.md

@@ -0,0 +1,13 @@
+---
+description: Search your memories for relevant past work
+allowed-tools: Bash
+---
+
+Search your memories using keywords. Returns the most relevant past tool calls, errors, and outputs.
+
+Usage: `/exe-search <query>`
+
+Run this command with the user's query:
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-search.js" "$ARGUMENTS"
+```

package/src/commands/exe/sessions.md

@@ -0,0 +1,25 @@
+---
+description: Show running employee tmux sessions
+allowed-tools: Bash
+---
+
+List all active employee sessions.
+
+Run:
+```bash
+tmux list-sessions -F '#{session_name} #{session_windows} #{?session_attached,(attached),}' 2>/dev/null || echo "NOT_IN_TMUX"
+```
+
+If NOT_IN_TMUX, say: "Not in a tmux session. Use `tmux new-session -s work` to start one."
+
+Format the output as a table. Employee sessions follow the naming convention `{name}-{exeSession}` (e.g., `yoshi-exe1`). Filter to only show sessions that match this pattern.
+
+```
+## Active Employee Sessions
+
+| Session | Employee | Parent Exe | Status |
+|---------|----------|------------|--------|
+
+Use `/exe-launch <names>` to start, `/exe-logs <name>` to tail output, `/exe-kill <name>` to stop.
+Switch sessions: Ctrl-b s (session picker)
+```

package/src/commands/exe/settings.md

@@ -0,0 +1,13 @@
+---
+name: settings
+description: Configure exe-os memory system settings
+allowed-tools: Bash
+---
+
+Configure auto-ingestion, auto-retrieval, and search mode.
+
+Run this command to open the settings menu:
+
+```bash
+node "$(npm root -g)/exe-os/dist/bin/exe-settings.js"
+```