fix(lock): distinguish denied ps from a held session lock

[milesangelo]

What Changed

• fm-lock.sh now classifies acquisition failures and prints a stable FM_LOCK_REASON=<reason> line to stderr — lock-held, ps-unavailable, or harness-detect-failed — with harness_pid() reporting through HARNESS_PID/HARNESS_FAIL_REASON globals so a denied/failed ps (e.g. a Codex sandbox) is no longer conflated with a clean ancestry walk that found no harness.
• fm-session-start.sh parses that reason to branch its read-only banner and NEXT STEP text: only lock-held prints the "another session holds the fleet lock" wording, while an unidentifiable-session reason prints an honest identity-unverifiable banner with bin/fm-lock.sh status plus session/process discovery commands, and both still skip every mutating step.
• Added tests/fm-lock.test.sh and cases in tests/fm-session-start.test.sh covering the reason classification and banner branching, and synced AGENTS.md, CONTRIBUTING.md, and the docs/ references to the new behavior.

Risk Assessment

✅ Low: A well-bounded, thoroughly tested correctness fix that only refines failure classification and banner text; behavior for existing paths is preserved and the sole output-parsing caller is updated in lockstep.

Testing

Completed 1 recorded test check.

Pipeline

Updates from git push no-mistakes

⏭️ **intent** - skipped

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

Closes #306

[milesangelo]

Rebased onto the latest main to clear the merge conflict.

The only real collision was in docs/scripts.md: this branch rewrote the fm-session-start.sh row to document the new FM_LOCK_REASON banner branching, while main (via #411) had added atomic-multi-ID-mv to the adjacent fm-bootstrap.sh row. Resolution keeps both — this branch's session-start wording and main's bootstrap wording. The other four touched files auto-merged cleanly.

All checks green after the rebase (Lint, no-mistakes gate, Behavior tests, Repo invariants); tests/fm-lock.sh and the added fm-session-start cases pass locally. No behavior or scope change from the rebase — same 9 files, same fix for #306.

[kunchenguid]

Thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#390 at 5b236230.}

[milesangelo]

Resolved! Thanks for the eyes on this!

[milesangelo]

using firstmate to pr on firstmate - you've created an intelligent and experience changing tool - ty!

[kunchenguid]

Thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#390 at 611c6a4f.}

[kunchenguid]

Automated reminder: thanks for the PR! This branch currently has a merge conflict with the base branch.

When you get a chance, please rebase onto (or merge) the latest base branch, resolve the conflict, and push. After that, checks will re-run and the PR will get looked at again.

_{Noted for firstmate#390 at f6a41ccf.}