agent-harness-plugins: Instructions file for GitHub Copilot

Shell script review instructions

Bundled scripts here run on macOS and Linux alike, so portability findings are welcome. These specific ones are not defects, and have been checked:

• git worktree list --porcelain -z is the only form that is parsed. The newline-delimited form splits a worktree path containing a newline across two apparent fields. NUL is the one byte a path cannot hold, so -z plus read -r -d '' is correct for every path a filesystem allows. A read -d '' loop also needs || [[ -n "${line}" ]] so a final field carrying no terminator is not discarded.

• flock is deliberately absent. macOS has no flock(1), which is why mutual exclusion here uses mkdir, which is atomic on every filesystem these scripts run on.

• kill -0 <pid> is a liveness test, not a terminate. It is the POSIX interface and keeps its name under the neutral-terminology convention, which exempts names the world already fixed.

• A "$(< path)" read is always preceded by -f and -r tests. That expansion fails during expansion rather than as a command, so a redirection on the assignment and a trailing || both miss it and Bash exits with its own unprefixed diagnostic. -r alone is insufficient: it is true for a readable directory. A scrut case in tests/scrut/repo-tooling.md enforces this.

• local is declared separately from command substitution (local x then x="$(cmd)") on purpose: local always returns 0 and would mask the command's exit code.

• # shellcheck disable=SC2016 at file scope is intentional in scripts built around jq filters. The $name tokens inside single-quoted jq programs are jq variables bound with --arg, not shell expansions.

• jq's sub and gsub take an optional third flags argument. sub/3 and gsub/3 are builtins alongside sub/2 and gsub/2, so sub("^copilot"; ""; "i") is a case-insensitive substitution, not a call with a surplus operand. Confirm with jq -n 'builtins | map(select(startswith("sub/") or startswith("gsub/")))', which lists all four. The same applies to scan/2, match/2, test/2, capture/2 and splits/2.

• jq -n with inputs reads every input record, the first included. -n binds . to null instead of the first record; it does not stop jq reading standard input, and inputs consumes all of it. printf 'a\nb\n' | jq -Rnc '[inputs]' prints ["a","b"]. This is the idiom for a single pass that stops early with label/break, as in notify's TURN_JQ.

• gh api --paginate without --jq concatenates REST array pages into one array. A paginated array endpoint yields a single JSON document, so a downstream type == "array" check holds at any page count and no flattening step is needed. --jq is what changes this: gh applies the filter to each page separately, so --paginate --jq 'length' over three pages emits three numbers. --slurp is for the array-of-arrays shape and is required only when page boundaries must be preserved, as in a probe that pipes into a standalone jq and takes last across all pages. The gh api --help line "Each page is a separate JSON array or object" describes the GraphQL and object-returning cases; do not read it as applying to REST array endpoints.

• fetch_thread_index in resolve-copilot-threads caps each thread at comments(first: 100) on purpose. The index is a lookup table, not the audit's source of comments: audit reads every review comment through the paginated REST endpoint and looks each one up in it. A comment beyond the first 100 in a thread is missing from the index and is reported as in no thread, so the cap can mislabel a reason but cannot make the audit report a clean surface. Do not ask for the nested connection to be paginated.

• notify's run_alerter stops each alerter with SIGKILL after WAIT_LIMIT seconds on purpose. SIGTERM and SIGINT make alerter remove the delivered banner; SIGKILL leaves it in Notification Center. Each run_alerter stops only its own child alerter, within 60 seconds at most, so it needs no PID start-time check, lock or shared state. Do not ask for a gentler signal, a lock or a start-time check.