From 7ee889a8f7a86f10b82aac0f38e237d0b7a9dc15 Mon Sep 17 00:00:00 2001
From: Viktor Kostetskyy
 <266837748+viktorkostetskyy-max@users.noreply.github.com>
Date: Tue, 5 May 2026 12:28:59 -0600
Subject: [PATCH] fix(session-handoff): restore Python 3.9 compatibility in
 scripts

`list_handoffs.py` and `check_staleness.py` use PEP 604 union syntax
(`X | None`) which requires Python 3.10+. On macOS, the system
`/usr/bin/python3` is Python 3.9.6 (Apple-shipped), causing both scripts
to fail with `TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'`
before reaching `main()`. SKILL.md instructs users to invoke `python` /
`python3`, so they hit this on a stock macOS install.

Add `from __future__ import annotations` to defer annotation evaluation,
restoring 3.9 compatibility without changing any signatures. Scripts use
no runtime introspection of annotations (`typing.get_type_hints`,
`inspect.signature(...).return_annotation` evaluation, etc.), so the
behavior is unchanged on 3.10+.

`create_handoff.py` and `validate_handoff.py` already worked on 3.9
because they only use PEP 585 lower-case generics (`list[str]`,
`tuple[bool, str]`), which 3.9 supports.

`dist/` is regenerated via `scripts/build_plugins.py` to keep source
and distribution copies in sync.

Tested on Python 3.9.6 (macOS system) and 3.11.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../skills/session-handoff/scripts/check_staleness.py           | 2 ++
 .../skills/session-handoff/scripts/list_handoffs.py             | 2 ++
 skills/session-handoff/scripts/check_staleness.py               | 2 ++
 skills/session-handoff/scripts/list_handoffs.py                 | 2 ++
 4 files changed, 8 insertions(+)

diff --git a/dist/plugins/session-handoff/skills/session-handoff/scripts/check_staleness.py b/dist/plugins/session-handoff/skills/session-handoff/scripts/check_staleness.py
index fbcb8ca..238189e 100755
--- a/dist/plugins/session-handoff/skills/session-handoff/scripts/check_staleness.py
+++ b/dist/plugins/session-handoff/skills/session-handoff/scripts/check_staleness.py
@@ -14,6 +14,8 @@
     python check_staleness.py .claude/handoffs/2024-01-15-143022-auth.md
 """
 
+from __future__ import annotations
+
 import os
 import re
 import subprocess
diff --git a/dist/plugins/session-handoff/skills/session-handoff/scripts/list_handoffs.py b/dist/plugins/session-handoff/skills/session-handoff/scripts/list_handoffs.py
index 3f38569..2ccfb16 100755
--- a/dist/plugins/session-handoff/skills/session-handoff/scripts/list_handoffs.py
+++ b/dist/plugins/session-handoff/skills/session-handoff/scripts/list_handoffs.py
@@ -12,6 +12,8 @@
     python list_handoffs.py /path     # List handoffs in specified path
 """
 
+from __future__ import annotations
+
 import os
 import re
 import sys
diff --git a/skills/session-handoff/scripts/check_staleness.py b/skills/session-handoff/scripts/check_staleness.py
index fbcb8ca..238189e 100755
--- a/skills/session-handoff/scripts/check_staleness.py
+++ b/skills/session-handoff/scripts/check_staleness.py
@@ -14,6 +14,8 @@
     python check_staleness.py .claude/handoffs/2024-01-15-143022-auth.md
 """
 
+from __future__ import annotations
+
 import os
 import re
 import subprocess
diff --git a/skills/session-handoff/scripts/list_handoffs.py b/skills/session-handoff/scripts/list_handoffs.py
index 3f38569..2ccfb16 100755
--- a/skills/session-handoff/scripts/list_handoffs.py
+++ b/skills/session-handoff/scripts/list_handoffs.py
@@ -12,6 +12,8 @@
     python list_handoffs.py /path     # List handoffs in specified path
 """
 
+from __future__ import annotations
+
 import os
 import re
 import sys