feat(init): install SessionStart auto-bootstrap hook (self-arming agents)

[ThinkOffApp]

Problem

After every IDE/CLI restart the room agent sat idle until Petrus manually typed /loop check rooms into the session. The 07-12 ask: "codewatchy should make that happen automatically" — restarts should leave the agent self-armed, for every IAK user, not just this machine.

Lineage

This productizes the prototype that has been running in production on the Mac mini since 2026-07-12 (~/.claude/scripts/session-bootstrap.sh + a hand-edited SessionStart entry in ~/.claude/settings.json). Same mechanism, de-petrus-ified.

Design

scripts/session-bootstrap.sh — a SessionStart hook script. It reads the hook stdin JSON (source: startup|resume|compact), counts backlog lines in the poller's notification file, and emits {"suppressOutput": true, "hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": ...}} instructing the agent to:

1. arm a persistent Monitor on the notification file if TaskList lacks one (instant wake, never a duplicate),
2. read + act on + clear any backlog that arrived while no session was running,
3. run the self-paced room loop with a fallback ScheduleWakeup (~1500s),
4. on compact, verify via TaskList instead of re-arming blindly.

Parameterization follows the existing script conventions (check-rooms-hook.sh, claudemb-poll.sh): IAK_NEW_FILE env, else config poller.notification_file, else /tmp/iak-new-messages.txt (the poller default / NOTIFY_FILE_DEFAULT); IAK_HANDLE env, else poller.handle; IAK_CONFIG_JSON env, else ide-agent-kit.json found relative to the script (repo root, or project root when installed into .claude/scripts/). Any failure degrades to no output + exit 0 — it can never block session start.

Wiring, both existing install paths:

• ide-agent-kit init --ide claude-code (and antigravity): copies the script into .claude/scripts/ and merges the hook into .claude/settings.json via the new src/claude-settings.mjs helper. Note: "Config already exists" no longer aborts init — every downstream step is individually guarded, so re-running init upgrades an existing install (that's how current users get this hook).
• scripts/install.sh: registers SessionStart alongside the existing UserPromptSubmit + Stop hooks in the same python ensure_hook merger.

Idempotency & safety

• Dedup by exact command string across all entries for the event (same semantics as install.sh's ensure_hook) — running init or the installer twice adds nothing.
• Unrelated hooks, permissions, and unknown settings keys are never touched; merge is additive only.
• settings.json.bak backup taken before the first mutating write (repo .bak convention); no backup churn on no-op runs.

Test coverage (test/session-bootstrap.test.mjs, 14 tests)

• hook emits valid SessionStart JSON for startup, compact, empty stdin, and non-JSON stdin
• backlog count reflects notification-file contents; missing file → 0
• config-file values (poller.notification_file, poller.handle) are honored; env overrides beat config
• settings merge: preserves unrelated hooks/permissions, idempotent, keeps pre-existing SessionStart entries, .bak backup on change, creates file when missing (temp-dir fixtures)
• end to end: iak init --ide claude-code twice in a temp cwd → exactly one hook entry

npm test: 134 pass, 0 fail. bash -n clean on both shell scripts; install.sh's python merger exercised standalone against a fixture (install → idempotent re-run → unrelated keys preserved → backup present).

Review

@codexmb — adversarial review requested per the cross-model PR review rule, before merge.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3510facf10

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".