feat(bin): add fm-relaunch.sh for on-demand session resume

[imemdev]

Intent

Developer (acting as an autonomous crewmate managed by "firstmate") tasked the agent with converting a hand-built prototype (a launchd LaunchAgent plist plus a payload script that opens Terminal running claude) into a proper, tracked repo tool: bin/fm-relaunch.sh with install/run/status/uninstall subcommands. The core requirement was safety: the generated launchd job must never self-trigger (no RunAtLoad, StartInterval, StartCalendarInterval, or watch-path keys) and can only fire via explicit launchctl kickstart/start, since the captain explicitly did not want an unattended auto-starting session. Requirements included idempotent install, macOS-only support with clear failure elsewhere, a colocated test file mocking system commands (launchctl/osascript/uname/id) that specifically asserts the forbidden auto-trigger keys are absent, documentation in docs/relaunch-tool.md per the "one-owner rule" (avoiding duplicating narrative in the script header or AGENTS.md), and cleanly superseding the existing same-named LaunchAgent without leaving conflicting duplicate jobs. The developer also required the work go through the no-mistakes validation pipeline (review, test, lint, document, push, PR) before completion, explicitly avoiding --yes so ask-user decisions remain with the human, and directed the agent to escalate rather than fix infrastructure blockers (spend limits, push permission errors) itself. A real security finding (AppleScript injection via unescaped $quoted_cd in the osascript call) was caught and fixed during the pipeline's review step. The developer (captain) ultimately resolved a GitHub push-permission blocker by forking and pushing manually, opening PR #894.

What Changed

• Add bin/fm-relaunch.sh with install/run/status/uninstall subcommands, generating a launchd LaunchAgent that opens Terminal running claude — the plist deliberately omits RunAtLoad, StartInterval, StartCalendarInterval, and watch-path keys so the job only fires via explicit launchctl kickstart/start, macOS-only with a clear failure message elsewhere.
• Fix an AppleScript injection risk by passing FM_HOME to osascript as an argv parameter instead of interpolating it into the quoted script string.
• Add tests/fm-relaunch.test.sh, mocking launchctl/osascript/uname/id to cover install idempotency, safety-key absence, and subcommand behavior.
• Document the tool in docs/relaunch-tool.md and add a row for it in docs/scripts.md.

Risk Assessment

✅ Low: Small self-contained script+tests+docs; core safety invariant (no launchd auto-trigger keys) verified present and tested; prior AppleScript injection already fixed via argv passing.

Testing

Ran the colocated mocked test suite (all 13 assertions pass, including the no-auto-trigger-key assertion) and additionally did a real, non-mocked install/status/uninstall cycle against actual launchctl/launchd on this macOS machine to confirm the generated LaunchAgent plist truly has no RunAtLoad/StartInterval/StartCalendarInterval/WatchPaths/QueueDirectories/KeepAlive keys and cleanly unloads; did not fire cmd_fire for real since that opens a live Terminal window/osascript trust dialog, which the mocked test already exercises safely.

Evidence: manual install output

installed: dev.firstmate.relaunch (/Users/a/Library/LaunchAgents/dev.firstmate.relaunch.plist), loaded with no automatic trigger

Evidence: manual status output

status: dev.firstmate.relaunch installed at /Users/a/Library/LaunchAgents/dev.firstmate.relaunch.plist, no automatic trigger key present
status: loaded in gui/501

Evidence: generated plist (real launchd install)

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>dev.firstmate.relaunch</string>
	<key>ProgramArguments</key>
	<array>
		<string>/Users/a/.no-mistakes/worktrees/6f88afbe7805/01KY78YWKRD02VK9Y2W68SJDJK/bin/fm-relaunch.sh</string>
		<string>fire</string>
	</array>
	<key>EnvironmentVariables</key>
	<dict>
		<key>FM_HOME</key>
		<string>/tmp/fm-relaunch-manual.fqNet1</string>
	</dict>
	<key>StandardOutPath</key>
	<string>/tmp/fm-relaunch-manual.fqNet1/state/fm-relaunch.log</string>
	<key>StandardErrorPath</key>
	<string>/tmp/fm-relaunch-manual.fqNet1/state/fm-relaunch.log</string>
</dict>
</plist>

Evidence: manual uninstall output

uninstalled: dev.firstmate.relaunch

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• bash tests/fm-relaunch.test.sh (13 mocked subcommand/safety tests, all ok)
• manual: FM_ROOT_OVERRIDE=<tmp> bin/fm-relaunch.sh install/status/uninstall against real launchctl on this Mac, inspected generated plist in ~/Library/LaunchAgents for absence of auto-trigger keys

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.