Claude Code's project-dir naming is lossy: /home/dev/client.acme and
/home/dev/client-acme both fold to -home-dev-client-acme and share one
directory of transcripts. Until this release the resolver did not fold the
same characters, so it simply missed such a directory. Now that it folds the
way Claude Code does, it finds the shared directory, and catchup has to
decide which transcripts in it belong to the project that asked.
Without that decision a catchup in one project prints the other project's
conversation into the fresh context. Reproduced against the previous commit
with a planted canary: the victim project's run emitted the donor's message
verbatim. The same run after this change emits a one line notice instead.
A transcript is skipped only when it positively records a different cwd.
Transcripts that record none are kept, because the field is not present in
every generation of the format. A directory whose transcripts all belong to
another project is reported rather than used, and mixed directories keep the
project's own transcripts, which is why the filter is per session rather
than a rejection of the whole directory: in a collision both projects live
there permanently, so rejecting the directory would cost the project its own
history for good.
Comparison goes through the same canonicalization the Codex path already
uses, case-insensitively on Windows.
tests/test_catchup_cross_project_guard.py covers the four cases at unit
level across every copy that carries the guard, plus two end to end runs of
the real script against a shared store: one asserting the canary never
appears, one asserting the project's own transcript still does.
Claude Code names ~/.claude/projects entries by folding every character
outside [A-Za-z0-9-] to '-', but three copies of session-catchup.py still
used a manual replace chain that handled only '/', '\' and ':'. Any project
path containing a dot, a space, or any other such character produced a name
Claude Code never writes, no candidate matched, and main() returned at the
exists() check with exit 0, so recovery after /clear was a silent no-op for
hidden directories such as ~/.dotfiles.
One of those copies is on a live install route. marketplace.json declares
"source": "./", so the plugin root is the repository root and the SKILL.md
restore block resolves ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py for
every plugin user on Linux, macOS or Git Bash. Measured against a real store
holding 89 sessions, the shipped resolver produced 0 bytes where the fixed
one produces 11336 and recovers 166 messages.
scripts/, .hermes and .mastracode now share the same normalize, sanitize and
candidate helpers as the canonical copy, keeping their existing function
names, signatures and the .mastracode Codex guard. Folding counts UTF-16
code units because Claude Code walks the name as UTF-16, so a non-BMP
character costs two dashes; that width was missing everywhere, which left
three real emoji projects unresolvable even in the canonical copy. Both
underscore spellings stay in the probe chain since stores using each are
live on disk, and the exact spelling is still probed first.
The folding rules were measured against 24 real stores whose recorded cwd
could be read; one model matches all 24. New
tests/test_catchup_store_resolution_parity.py discovers the copies with
git ls-files and runs a single vector table through each, so this drift
fails the suite instead of hiding in one file. .kiro is excluded because it
ships a different program that never reads ~/.claude/projects.
The Stop scalar never dispatched on macOS or Linux (the PowerShell branch
was always selected because check-complete.ps1 ships on every platform)
and was a silent no-op anywhere CLAUDE_SKILL_DIR was unset (the :- install
path fallback can never substitute because the probed variable is always a
non-empty string). Both the legacy completion advisory and the v3
completion gate were dead in those environments. The scalar now selects
targets by file existence and dispatches by platform, PowerShell only
under MINGW/MSYS/CYGWIN, sh elsewhere. Windows output is unchanged.
Patched in all 14 SKILL.md variants that carry the scalar.
session-catchup probed a ~/.claude/projects name that Claude Code never
writes for POSIX paths (leading dash stripped) or paths containing an
underscore (replaced with a dash), so recovery after /clear silently
found nothing there. The mapper now probes the exact spelling first,
keeps both legacy spellings for stores created by older versions, and
settles ambiguity via the cwd recorded in the newest session file.
Propagated to every shipped copy including the older-generation root,
.hermes, and .mastracode scripts.
Also: the attestation SHA cache is keyed on the absolute plan path so two
projects can no longer share a slot and report a false PLAN TAMPERED;
resolve-plan-dir.ps1 reaches parity with the sh resolver (slug filter,
task_plan.md requirement in the newest-dir scan, fail-closed containment);
ledger-append.sh no longer truncates summaries mid-codepoint (UTF-8-safe
trim via iconv with a pure-sh fallback).
New long-run features, all opt-in or additive: structure-aware injection
(PWF_INJECT=smart or an inject-smart .mode token) keeps the active phase,
phase counts, and the last three decisions in the window late in long
plans; a Next Step section in both plan templates plus a sixth reboot
question; session-catchup annotates tool results (ok or FAILED with the
first error line) instead of only listing attempts.
Infrastructure: macos-latest joins the CI matrix, a BSD-userland
simulation harness runs the script fleet without realpath, readlink,
flock, or sha256sum on the Linux leg, and .gitattributes pins LF for
scripts. SEO surfaces: llms.txt rewritten as a Q&A page, three
problem-query docs pages, plugin.json and CITATION.cff keyword hygiene.
Suite grows from 217 to 301 passed, 11 skipped, on Windows and both
existing CI legs; default hook output stays byte-identical to v2.43
(legacy invariant proven by the existing invariant tests).
get_project_dir_claude only replaced forward slashes, so a Windows path
(C:\Users\... or Git Bash's /c/Users/...) never sanitized to Claude's real
project directory name, and the function silently returned early every time.
Three open() calls also had no explicit encoding, so a session log with any
non-ASCII content raised UnicodeDecodeError on Windows' default cp1252 codec,
an error the bare except clauses swallowed. Together these meant the "resume
after /clear" feature did nothing on Windows, with no visible error.
Fixed by branching on whether the path looks Windows-shaped (contains ':' or
'\') before sanitizing, converting Git Bash drive-letter paths first, and
adding encoding='utf-8', errors='replace' to the three reads. Genuine Unix
absolute paths take the untouched legacy branch, so macOS/Linux behavior is
unchanged.
tests/test_path_fix.py previously reimplemented the sanitizer instead of
importing the real module ("avoids import issues" per its own comment), so
the suite stayed green while the shipped script stayed broken. It now loads
scripts/session-catchup.py via importlib and exercises the actual function,
plus a regression case for the untouched Unix branch.
PreCompact hook fires on /compact and autoCompact. When task_plan.md is
present, surfaces a reminder to flush in-context progress to progress.md
before compaction completes and prints the active Plan-SHA256 if attested.
Stays silent without a plan. Exit 0 always; never blocks compaction.
/plan-goal composes with Claude Code's /goal (v2.1.139, May 12 2026).
Derives a termination condition from the active plan so /goal stops the
agent when the plan-file is genuinely complete, not just when the
conversation looks done.
/plan-loop composes with /loop (v2.1.72+). Default 10-minute tick re-reads
planning files, runs check-complete, nudges a progress.md entry if the
last tick produced no change. templates/loop.md ships a planning-aware
default for ~/.claude/loop.md so bare /loop works grounded in the plan.
OpenCode session-catchup rewritten for the SQLite migration (sst/opencode
dev @ 2026-05-14). Reads ${XDG_DATA_HOME:-~/.local/share}/opencode/opencode.db
read-only via URI, scopes by session.directory, surfaces unsynced planning
edits. Verified against a real 162 MB OpenCode database (94 sessions, 56
unsynced parts correctly extracted from the lovable-at-home directory).
Codex gains a PermissionRequest adapter that surfaces a one-line plan
reminder when an active plan exists. Read-only; never blocks.
Tests: +19 covering PreCompact behavior, slash command file structure,
OpenCode SQLite catchup with a synthetic schema-matching DB, and Codex
PermissionRequest emit/silent behavior. 98 tests passing.
Deliberately not changed: paths glob (auto-invocation behavior risk),
wholesale !command swap (would freeze attestation hash and defeat v2.37
tamper gate), native Plan Mode panel integration (no plugin API
documented), language variant consolidation (separate breaking-change
track). PreCompact lives in the canonical SKILL.md + 5 language variants
+ clawhub-upload; other IDE mirrors keep their existing compaction
hooks until per-IDE PreCompact adapters land in a future release.
OpenCode uses different session storage (.json at ~/.local/share/opencode/) than Claude Code (.jsonl at ~/.claude/projects/). Session catchup now detects the IDE and provides a clear workaround message instead of silently failing.
- Added IDE detection (checks env vars and directory structure)
- OpenCode users get helpful message to manually read planning files
- Claude Code functionality unchanged
- Updated OpenCode docs with known limitations section
Fixes#74
The session-catchup.py script now properly scans across ALL sessions to find
unsynced context since the last planning file update.
Changes:
- Skip the current session (most recently modified)
- Find the most recent planning file update across all previous sessions
- Collect ALL conversation from that point forward, across all sessions
- Show session markers [Session: xxx...] when context spans multiple sessions
- Include intermediate sessions that have no planning updates but have work
- Show up to 100 messages (was 20), with note if truncated
Example: If planning was updated in session A, then work continued in sessions
B and C without updates, the catchup now shows context from A, B, and C.
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
Automatically detect and recover unsynced work from previous sessions
when context fills up and user runs /clear.
New features:
- session-catchup.py: Analyzes previous session JSONL to find unsynced context
- Recovery triggered automatically when invoking /planning-with-files
- PreToolUse hook now includes Read/Glob/Grep for better attention management
Optimal workflow:
1. Disable auto-compact in Claude Code settings
2. Start fresh session
3. Run /planning-with-files when ready for complex task
4. Work until context fills up
5. Run /clear
6. Run /planning-with-files again — automatically recovers where you left off
How recovery works:
- SKILL.md instructs Claude to first run session-catchup.py
- Script checks ~/.claude/projects/ for previous session JSONL
- Finds last planning file update, extracts conversation after that point
- Claude updates planning files based on catchup + git diff
Changes:
- SKILL.md: Added session recovery section, preserved all original content
- README: Added optimal workflow and setup instructions
- Removed SessionStart hook (doesn't work per Issue #24)
- Version bumped to 2.2.0
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
OthmanAdi