Summary

Phase 1 of the hooks-session-cli RFC (memtomem-docs#24): adds the CLI
primitives a SessionStart hook needs without orphaning prior
sessions.

• mm session start --idempotent returns the active session for
  the same --agent-id instead of creating a new one. Cross-agent
  collisions auto-end the previous session.
• mm session start --auto-end-stale=<duration> (e.g. 24h,
  7d) closes any active session older than the duration before
  resolving idempotency. Opt-in only.
• mm session start --json emits {"session_id": ..., "resumed": bool, "stale_ended": [...]} for hook parsing.

Storage backing: find_stale_active_sessions(started_before)
filters on ended_at IS NULL AND started_at < ? — a dedicated
method instead of forcing every caller to load list_sessions and
filter in Python.

Why this is Phase 1 only

The plugin's hooks.json SessionStart entry, the docs example in
docs/guides/integrations/claude-code.md, and the
TestPluginHooksDocsParity extension all ship in a follow-up PR.
Decoupling lets reviewers gate the CLI contract before the hook
surface depends on it. PR #536 documented the same staging.

Verification

• 6 unit tests on mm session start covering RFC §Verification's
  five behaviours (same-agent idempotent, cross-agent end+new, manual
  end then fresh, auto-end-stale, JSON shape) plus an
  invalid-duration guard.
• 1 storage test on find_stale_active_sessions against real
  SQLite — avoids the AsyncMock-hides-SQL-bugs trap when the filter
  predicate is non-trivial.
• ruff check, ruff format --check, mypy (advisory) all
  green on the changed files.

Open questions decided in this PR (§ in RFC)

• Q1 same-agent semantics → return existing (recommended)
• Q2 cross-agent collision → end old, start new (recommended)
• Q4 caller identification → --agent-id literal (recommended)
• Q5 race window → no advisory lock (recommended)
• Q6 manually-ended state file → treat as advisory, create fresh (recommended)

Q3 (default stale duration) is a docs decision, defers to Phase 2.

Test plan

• Reviewer: confirm the JSON output keys match RFC §Implementation
  sketch (session_id, resumed, stale_ended)
• Reviewer: confirm --auto-end-stale parses 24h/7d/
  30m/45s and rejects garbage with a Click error
• Reviewer: confirm Phase 2 (docs + plugin hooks.json) staying in
  a follow-up PR matches the project's preferred cadence

🤖 Generated with Claude Code