@symerian/symi 2.6.41 → 2.6.42

package/skills/long-task/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: long-task
+description: Run long operations (deep scans, brute-forces, big builds, exhaustive enumeration) without hitting the agent-turn timeout. Detaches the command with setsid+nohup and schedules a cron monitor that polls status every 2-3 minutes. Use when a single exec call may exceed 15 minutes (deep nmap `-sS -sV -O` on /24 or larger, full hydra/gobuster/ffuf/masscan sweeps, multi-hour builds).
+---
+
+# Long-Running Task — detach + cron monitor pattern
+
+Deep scans (`nmap -sS -sV -O` on a /24, comprehensive `-sC` sweeps, full TCP/UDP, long brute-forces, big builds) routinely run 25–60 minutes. The agent-turn timeout (`agents.defaults.timeoutSeconds`, default 1800 = 30 min) is a hard ceiling, and a foreground-blocked exec tool call will SIGTERM the subprocess when the turn ends. **Do not foreground long tasks.** Use this two-part pattern instead.
+
+## Part 1 — Detach the task
+
+Launch with the helper script bundled with this skill:
+
+    <skill-dir>/scripts/detach-task.sh <task-id> <workdir> <command...>
+
+Where:
+
+- `<task-id>` is a short identifier you pick (e.g. `scan-192-168-10`)
+- `<workdir>` is a directory the state files will be written into (agent workspace is fine)
+- `<command...>` is the literal command you want to run
+
+The script creates in `<workdir>`:
+
+- `task-<id>.pid` — PID of the detached process
+- `task-<id>.cmd` — the literal command line
+- `task-<id>.started` — ISO-8601 start timestamp
+- `task-<id>.log` — merged stdout/stderr
+- `task-<id>.status` — `running` while alive, `complete rc=<N>` after exit
+
+After running, **return control to the user immediately** with: task id, PID, log path, your ETA, and a note that a cron monitor will be scheduled.
+
+## Part 2 — Schedule the cron monitor
+
+Use the `cron` tool with `action: add`. Schedule every 2–3 minutes. The job prompt must be self-contained — include the task-id, PID, log path, and status path literally, since a future agent turn will receive only that prompt.
+
+Example job prompt:
+
+> Check if PID <pid> is alive (`kill -0 <pid> 2>/dev/null`).
+> If alive: tail -n 20 <log-path>, post one-sentence progress update.
+> If not alive: read <status-path> and tail <log-path>, post final summary, then call the cron tool with `action: remove, id: <this-cron-id>` to clean up.
+
+## Part 3 — Cleanup
+
+The monitor cron job is responsible for removing itself when it detects `status=complete`. Do not leave stale monitors running.
+
+## Why this works
+
+- `setsid` puts the subprocess in a new session — it survives SIGHUP.
+- `nohup` ignores SIGHUP directly as belt-and-braces.
+- The outer shell exits immediately, so the agent-turn abort (which kills the process tree of the shell the agent spawned) never reaches the detached task — it's no longer a descendant.
+- Each agent turn stays short (initial detach <1 min, each cron check <30 sec, final summary <1 min), so the default 1800s ceiling never fires.
+
+## When NOT to use this pattern
+
+- Short scans (single host, small port range) that complete in under 10 minutes — foreground exec is simpler.
+- Interactive commands that need a TTY — the script closes stdin and redirects stdout/stderr.
+- Tasks where you need to stream output back to the user in real time — the cron-monitor pattern polls at 2–3 min intervals, not live.

package/skills/long-task/scripts/detach-task.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# detach-task.sh — launch a long-running command fully detached from the
+# calling agent turn, so it survives the agent-turn timeout (default 30 min).
+#
+# Usage:
+#   detach-task.sh <task-id> <workdir> <command...>
+#
+# Creates in <workdir>:
+#   task-<id>.pid       — PID of the detached process
+#   task-<id>.cmd       — literal command line (for future agent turns to see)
+#   task-<id>.started   — ISO-8601 start timestamp
+#   task-<id>.log       — combined stdout + stderr (grows as task runs)
+#   task-<id>.status    — "running" while alive, "complete rc=<N>" after exit
+#
+# Exit code: 0 on successful spawn (PID recorded), 1 on invalid args.
+#
+# Design notes:
+# - setsid + nohup + disown: triple-armor against SIGHUP when the parent
+#   shell exits. The subprocess gets its own session.
+# - stdin closed, stdout/stderr redirected to the log file. No terminal.
+# - The wrapper shell exits immediately after spawning; does NOT wait.
+# - On process exit, an inner wrapper writes "complete rc=<N>" to the
+#   status file so a future agent turn can detect completion without
+#   racing with the cron monitor's polling.
+
+set -euo pipefail
+
+if [[ $# -lt 3 ]]; then
+  echo "usage: $0 <task-id> <workdir> <command...>" >&2
+  exit 1
+fi
+
+task_id="$1"
+workdir="$2"
+shift 2
+
+mkdir -p "$workdir"
+pid_file="$workdir/task-${task_id}.pid"
+cmd_file="$workdir/task-${task_id}.cmd"
+started_file="$workdir/task-${task_id}.started"
+log_file="$workdir/task-${task_id}.log"
+status_file="$workdir/task-${task_id}.status"
+
+printf '%s\n' "$*" > "$cmd_file"
+date -u -Iseconds > "$started_file"
+echo "running" > "$status_file"
+
+setsid nohup bash -c "
+  \"\$@\" > '$log_file' 2>&1
+  rc=\$?
+  echo \"complete rc=\$rc\" > '$status_file'
+" -- "$@" < /dev/null > /dev/null 2>&1 &
+
+pid=$!
+disown "$pid" 2>/dev/null || true
+printf '%d\n' "$pid" > "$pid_file"
+
+echo "spawned task=$task_id pid=$pid log=$log_file status=$status_file"