sno-ai/sno-station-skills / skills/H-reporting-and-visibility/agentic-time-estimate/skill
agentic-time-estimate
VerifiedAnswer how long agent work will take, how much longer active work needs, or what clock time applies. Estimate full AI-agent wall time, measure active progress first, and get owner-facing times from `sno report-time`. Never estimate human-developer time.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 37.4 KB |
| references/VALIDATION-REPORT.md | markdown | 491 B |
| references/case-table.md | markdown | 2.1 KB |
| references/train-set.tsv | other | 6.0 KB |
| references/unit-rates.md | markdown | 7.9 KB |
| scripts/selftest/calibration.t | other | 789 B |
| scripts/selftest/run-selftest.shexecutable | script | 1.7 KB |
| scripts/time-leftexecutable | script | 9.5 KB |
scripts/time-left
View on GitHub#!/usr/bin/env bash
# time-left — deterministic facts about work already in flight. No estimating here:
# this script reports only what a process or a checklist actually says, so the
# model's judgment starts from measured ground instead of a remembered figure.
#
# time-left --find <pattern> -> every candidate pid, with how long each has run:
# pid 3024701 2h07m elapsed pytest -q tests/
# Own shell and its ancestors are excluded, because a
# loose pattern otherwise matches the shell asking.
# time-left --pid <pid> -> one of two fact lines:
# deadline: <local/UTC pair> (a timeout wrapper on
# this pid OR just above
# it: the hard instant)
# running: <H>h<M>m elapsed — no deadline exists
# (no timeout wrapper)
# time-left --tasks <file> -> checklist progress, counted not judged:
# tasks: <done>/<total> done (<pct>%), <open> open
# 0 open does NOT mean 0 time left: close-out work
# (final review, release, hand-over) is never a checkbox.
#
# Exit: 0 facts printed · 2 nothing determinable (dead pid, unreadable file,
# no checkboxes). Exit 2 means "measure differently or fall back to judgment",
# never "assume zero".
set -Eeuo pipefail
die() { printf 'time-left: %s\n' "$*" >&2; exit 2; }
# --pid and --find read elapsed time from `ps -o etime` ([[dd-]hh:]mm:ss), which procps (Linux) and
# BSD ps (macOS) both print; procps-only `etimes` does not exist on macOS. Without a working `ps`
# a live pid would be reported as already finished, so stop here with the real cause.
need_procps() {
if ! command -v pgrep >/dev/null 2>&1 || ! ps -o etime= -p "$$" >/dev/null 2>&1; then
die "requires ps (with the etime column) and pgrep; --tasks works without them"
fi
}
# elapsed_seconds <pid>: whole seconds the process has run; prints nothing when it is gone or the
# value is unreadable. 10# keeps a zero-padded field such as 08 from being read as octal.
elapsed_seconds() {
local t d=0 h=0 m s
t=$(ps -o etime= -p "$1" 2>/dev/null | tr -d ' ') || true
case "$t" in *-*) d=${t%%-*}; t=${t#*-};; esac
case "$t" in
*:*:*) h=${t%%:*}; t=${t#*:};;
esac
m=${t%%:*}; s=${t#*:}
case "$d$h$m$s" in ''|*[!0-9]*) return 0;; esac
[ "$m" != "$t" ] || return 0
printf '%d\n' $(( 10#$d * 86400 + 10#$h * 3600 + 10#$m * 60 + 10#$s ))
}
case "${1:-}" in
-h|--help)
sed -n '/^# time-left —/,/^# never "assume zero"\./p' "$0" | sed 's/^# \{0,1\}//'
exit 0
;;
--pid)
[ $# -eq 2 ] || die "usage: --pid <pid>"
need_procps
case "$2" in ''|*[!0-9]*) die "--pid takes a pid, got '$2'";; esac
pid=$2
comm=$(ps -o comm= -p "$pid" 2>/dev/null | tr -d ' ') \
|| die "pid $pid is not running — nothing is left to wait for, or the pid is wrong"
[ -n "$comm" ] || die "pid $pid is not running — nothing is left to wait for, or the pid is wrong"
# The deadline lives on the WRAPPER, but the pid a caller has in hand is the
# worker -- `timeout 1800 pytest` is two processes, and asking the worker gives
# "no deadline exists" for a job whose stop instant is fully known. Walk up
# and find the wrapper instead of making the caller know
# this. Bounded: a wrapper is the immediate parent or very near it, and an
# unbounded walk would eventually reach init and report ITS deadline.
wrapper=""; probe=$pid; hops=0
while [ "$hops" -lt 4 ] && [ "$probe" -gt 1 ]; do
# `|| true` on every ps capture that may legitimately come back empty: under
# `set -o pipefail` a dead pid makes the pipeline fail, and the assignment IS
# the failing command, so `set -e` kills the script BEFORE the empty-value
# guard on the next line can run, producing no error message.
pcomm=$(ps -o comm= -p "$probe" 2>/dev/null | tr -d ' ') || true
# macOS ps prints comm as the full path when the wrapper was started by path.
if [ "${pcomm##*/}" = "timeout" ]; then wrapper=$probe; break; fi
probe=$(ps -o ppid= -p "$probe" 2>/dev/null | tr -d ' ') || true
case "$probe" in ''|*[!0-9]*) break;; esac
hops=$(( hops + 1 ))
done
if [ -n "$wrapper" ]; then
# sno report-time reads the wall off the wrapper's argv and refuses to guess --
# that refusal propagates as our exit 2, which is correct: a half-read
# deadline is worse than none.
command -v sno >/dev/null 2>&1 || die "sno not found on PATH (it provides report-time; install Sno Station)"
deadline=$(sno report-time --pid "$wrapper") || exit 2
if [ "$wrapper" = "$pid" ]; then
printf 'deadline: %s\n' "$deadline"
else
printf 'deadline: %s (from wrapper pid %s)\n' "$deadline" "$wrapper"
fi
else
etimes=$(elapsed_seconds "$pid")
case "$etimes" in ''|*[!0-9]*) die "pid $pid: cannot read elapsed time";; esac
printf 'running: %dh%02dm elapsed — no deadline exists (no timeout wrapper)\n' \
$(( etimes / 3600 )) $(( (etimes % 3600) / 60 ))
fi
;;
--find)
# Finding the pid is where the caller reaches for `pgrep -f <pattern>`, and a
# loose pattern matches the CHECKING shell: the pattern text sits in that
# shell's own command line, so it ranks first and reports 0h00m elapsed for a
# job that has run for hours. Own process and own ancestry are excluded here so
# the caller cannot step on it.
[ $# -eq 2 ] || die "usage: --find <pattern>"
need_procps
# Whitespace-only is the shape an agent's failed extraction actually takes, and
# it is NOT empty: it passes a -n test and then matches nearly every process.
# A whitespace-only search can return an unrelated login shell as the job.
case "${2:-}" in
*[![:space:]]*) : ;;
*) die "--find needs a pattern with real characters, got only whitespace — the extraction that produced it failed" ;;
esac
self_chain=" $$ "
probe=$PPID; hops=0
while [ "$hops" -lt 12 ] && [ "${probe:-0}" -gt 1 ]; do
self_chain="$self_chain$probe "
probe=$(ps -o ppid= -p "$probe" 2>/dev/null | tr -d ' ') || true
case "$probe" in ''|*[!0-9]*) break;; esac
hops=$(( hops + 1 ))
done
# pgrep's three statuses must not collapse into one. Captured explicitly: left
# inside the loop's heredoc a nonzero status aborts the script under `set -e`,
# exiting 1 with no message -- a status this contract does not define and a
# caller reads as "not zero, keep going". And a MALFORMED pattern (status 2)
# reported as "no process matches" tells the caller the job has finished when it
# was never searched for, which sends it to the guessing fallback with a
# measurable fact still unmeasured.
pgrep_rc=0
matches=$(pgrep -f -- "$2" 2>/dev/null) || pgrep_rc=$?
case "$pgrep_rc" in
0) : ;;
1) matches="" ;;
*) die "--find: '$2' is not a usable search pattern (pgrep status $pgrep_rc) — nothing was searched for, so this is not evidence the job finished" ;;
esac
found=0
while read -r cand; do
[ -n "$cand" ] || continue
case "$self_chain" in *" $cand "*) continue;; esac
etimes=$(elapsed_seconds "$cand")
case "$etimes" in ''|*[!0-9]*) continue;; esac
args=$(ps -o args= -p "$cand" 2>/dev/null | cut -c1-90) || true
printf 'pid %s %dh%02dm elapsed %s\n' \
"$cand" $(( etimes / 3600 )) $(( (etimes % 3600) / 60 )) "$args"
found=$(( found + 1 ))
done <<EOF
$matches
EOF
[ "$found" -gt 0 ] \
|| die "no process matches '$2' (excluding this shell) — it already finished, or the pattern is wrong"
;;
--tasks)
[ $# -eq 2 ] || die "usage: --tasks <file>"
file=$2
[ -f "$file" ] && [ -r "$file" ] || die "cannot read tasks file: $file"
# `-`, `*`, `+` and `1.` are all legal list bullets. grep -c exits 1 on zero
# matches, which is a count here, not a failure.
MARK='^[[:space:]]*([-*+]|[0-9]+[.)])[[:space:]]+'
done_n=$(grep -c -E "${MARK}\[[xX]\]" -- "$file") || true
open_n=$(grep -c -E "${MARK}\[[[:space:]]?\]" -- "$file") || true
total=$(( done_n + open_n ))
[ "$total" -gt 0 ] || die "no checkboxes found in $file — progress is not countable here"
# A checkbox row this counter did not count silently shrinks the denominator, and
# that error runs in ONE direction: a higher percent done -- the direction that
# makes an agent report unfinished work as finished. Refuse over a partial count.
# An OPTIONAL bullet then the box. Deliberately not "any word then a box":
# that shape matches ordinary prose containing "[x]" and would refuse a healthy
# file, and a guard that blocks the working path is worse than the hole it fills.
seen=$(grep -c -E '^[[:space:]]*([-*+]|[0-9]+[.)])?[[:space:]]*\[[ xX]\]' -- "$file") || true
[ "$seen" -le "$total" ] || die "$file has $seen checkbox-style rows but only $total are countable — an uncounted row would overstate progress; report the file, not a number"
printf 'tasks: %d/%d done (%d%%), %d open\n' \
"$done_n" "$total" $(( done_n * 100 / total )) "$open_n"
;;
'')
die "usage: time-left --find <pattern> | --pid <pid> | --tasks <file> (--help for details)"
;;
*)
die "unknown argument '$1' — usage: time-left --find <pattern> | --pid <pid> | --tasks <file>"
;;
esac
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Unverified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |