Session Kit v0.2.0 (Public Beta)

Two sessions could show the same colour, and the file that did most of the work
had grown to 7,008 lines. This release fixes the first and restructures the
second without changing what anything does.

Colours

Sessions could collide for two independent reasons, and fixing one left the
other in place.

Claude Code and Codex drew from a single eight-name palette, so they collided
across providers. They now have separate palettes and cannot share a colour at
all. Claude keeps red, blue, green, yellow, purple, orange, pink,
cyan — that set is fixed by Claude Code, whose /color accepts those eight
names and rejects everything else. Twenty-two names were probed against Claude
Code 2.1.223 with known-good and known-bad controls to establish that, so the
constraint is measured rather than assumed. Codex resolves its colour from a
theme file this kit ships and applies no allow-list, so it now has six names of
its own: lime, magenta, silver, sand, sky, sea.

Separately, a colour comes from an identity hash, and hashes collide well before
the names run out. Measured on a live installation: eight Claude sessions landed
on seven colours, two sharing while another sat unused. A session now keeps its
identity colour unless a live session of the same provider already holds it, in
which case it takes the next free name. sp color reconcile settles sessions
that already share one, in a single repeatable pass.

The inventory is now a package

lib/session_inventory.py held configuration, process inspection, provider
discovery, inventory assembly, state, naming, recovery, rendering, and CLI
parsing. It is now 2,905 lines of CLI parsing and compatibility wrappers, with
the implementation in twenty-one focused modules under
lib/sessionkit_inventory/.

Nothing changed about what it does. The entry point stays executable and
importable with identical symbols, signatures, exit codes, JSON fields and
output; no package module imports it; the graph is acyclic.

Rollback across a palette change

Found while certifying the real upgrade path rather than by a test: rolling back
from this release failed outright, because the installer required every theme
name it knew from whichever release it was installing, and older releases never
shipped the six new ones. The escape hatch has to work against releases that
predate the change being rolled back. Themes now come from the release being
installed, which also fixes the mirror case — the first update after a palette
change ran under the previous launcher and installed the older, smaller set.

Also

session-kit doctor reports the shpool binary fingerprint state, distinguishing
none recorded, malformed, and no longer matching. The watchdog already compared
the running daemon against that value, but nothing reported when the comparison
had gone inert, and a stale fingerprint reports a change on every pass until the
report stops being read. The shpool patch guide now gives the exact command to
record it.

Documentation has been rewritten across every page, including a troubleshooting
entry for the failure where every session becomes unreachable at once — the one
condition no Session Kit command can diagnose, because every command blocks for
the same reason the sessions do.

Upgrading

session-kit update does not restart, stop, signal, attach to, or detach from
shpool, and a running command finishes on the release it started with. Rolling
back to 0.1.x is safe: older code ignores a colour override it does not
recognise and falls back to its own palette.

Session Kit is a public beta, published as a GitHub prerelease. Release assets
are named by source commit rather than by version.

Session Kit v0.1.6 (Public Beta)

A patch release for one problem: shpool 0.11.0 can deadlock on detach and take
every managed session down at once. If you run Session Kit on stock shpool
0.11.0, you are exposed to this.

The failure

Every managed session becomes unreachable. The daemon is alive and still
accepting connections, but every list, attach, and detach blocks forever. It
does not recover on its own.

Upstream handle_detach holds the global session-table lock across an unbounded
send and receive on two rendezvous channels. A client whose socket has stopped
draining leaves its shell-to-client thread blocked in write() rather than in
its select loop, so the handshake never completes and the global lock is parked
indefinitely. One stalled SSH window is enough to take down every session.

The fix

New optional patch 0004 restructures handle_detach into resolve-under-lock,
drop the lock, bounded handshake, then a brief re-lock for bookkeeping. That is
the pattern upstream already uses for the session-message detach in the same
file; handle_detach was the only call site on that channel that was neither
scoped nor bounded.

It applies cleanly to pristine v0.11.0 and is independent of 0001-0003.
See the patch notes
before deciding what to run.

Also in this release

The write-up for patch 0001 has been corrected. It addresses heartbeat
acknowledgement timeouts and would not have prevented this deadlock; the notes
now say so and point at 0004 first.

The watchdog now tells an unset notifier apart from a broken one. With
SESSION_KIT_WATCHDOG_NOTIFY unset it logged that the empty string was not
executable, which reads like a misconfigured path rather than absent
configuration. The watchdog raises no alert anywhere until you configure a
notifier — it detects and logs either way, but with nothing wired up the only
record is the owner-only watchdog log. This is now documented under
Watchdog alerts.

Upgrading

session-kit update does not restart, stop, signal, attach to, or detach from
shpool, and running commands finish on the release they started with. Applying
the shpool patch is a separate, manual step: it rebuilds the shpool binary, and
nothing in this release does that for you.

Session Kit is a public beta, published as a GitHub prerelease. Release assets
are named by source commit rather than by version.

Session Kit v0.1.5 (Public Beta)

Session Kit v0.1.5 is a public beta for Linux with systemd and macOS 14 or newer.

Changed

• The full picker and provider-exit test suites now run on macOS CI through the
  native Darwin process adapter, replacing a Linux-only harness that read
  process generations straight from /proc. The one test that genuinely needs
  /proc skips on Darwin instead of failing.

Fixed

• Removed a picker repaint guard that conditioned redraws on a terminal input
  probe which always reports an empty queue in canonical mode. Repaints never
  consume queued characters, so a half-typed search now survives a live menu
  repaint on Linux and macOS alike.
• Read-only install and doctor probes reach the current user's systemd manager
  through its documented local-machine transport when the direct private
  socket is unavailable; the degraded socket is reported as a warning and
  service-control commands stay fail-closed.
• Claude's persisted agent-name record outranks its later generated window
  label, so an exact sp self-name converges to ready instead of remaining
  pending after a successful native write.
• An exact live-palette color is reserved and persisted after a failed Claude
  pre-bake, before the detached session can be attached, instead of falling
  back to a collision-prone identity hash.
• Warning-only migration audits cover bounded provider versions, private Codex
  themes, naming instructions and hooks, active kill switches, and the private
  release acceptance record.
• Provider project discovery excludes inaccessible paths while retaining
  readable shared repositories, and honors CODEX_HOME consistently during
  discovery and theme installation.

Verification for this release

• Continuous integration: Ubuntu 22.04 and 24.04 on Python 3.10–3.13; native
  macOS 15 runners on Apple Silicon (arm64) and Intel (x86_64) with Python
  3.13 and Homebrew Bash; ShellCheck, Ruff, mypy, branch coverage, public
  export equality, documentation links, and the optional shpool 0.11.0 patch
  build.
• Real-device acceptance, macOS: macOS 26.5.1 on Apple Silicon (arm64) with
  Homebrew Bash 5.3.15, Homebrew Python 3.11, and shpool 0.11.0 — the full
  macOS suite passed on-device at this exact commit, including the picker and
  provider-exit suites that CI runners alone cannot prove.
• Real-device acceptance, Linux: AlmaLinux 10.2 with systemd — preflight,
  non-interactive install, and doctor completed cleanly in a fresh login
  environment.
• The release archive is byte-reproducible: two independent builds of this
  commit produced identical archives, checksums, and provenance records.

Verify the download before installing:

sha256sum --check session-kit-70c4902fec18ba52f4b74876dafa223af72f93de.sha256

Session Kit v0.1.4 (Public Beta)

Session Kit v0.1.4

This public beta adds first-install project discovery and fixes exact provider
identity, naming, color, and child-activity handling.

Added

• Discovers existing Claude Code and Codex project folders from their bounded
  local configuration, history, and thread stores without crawling the home
  directory.
• Shows discovered folders during the first interactive install and imports all
  of them by default.
• Adds rerunnable session-kit projects discover, import, list, and add
  commands.
• Preserves manual shortcuts, creates owner-only backups, and assigns distinct
  provider aliases when Claude Code and Codex use the same folder.

Fixed

• Associates a managed Codex App Server's one open remote-TUI rollout with its
  Session Kit terminal, restoring the exact thread title and launch color.
• Refuses ambiguous App Servers and excludes editor rollouts from ordinary Codex
  process identity.
• Defers unsafe in-window Codex title refreshes while the provider is attached or
  working.
• Counts only active Codex child threads and keeps internal refresh markers out
  of ordinary dashboard rows.

Verification

• The private source passed 412 tests. The exact public export passed 410 tests,
  clean-install preflight, ShellCheck, Ruff, bytecode, type, documentation,
  privacy, reachable-history, export-completeness, and release gates.
• GitHub Actions run 30875538573 passed all 12 jobs: native macOS arm64 and
  x86_64, Ubuntu 22.04 and 24.04 with Python 3.10 through 3.13, quality/export,
  and the optional shpool patch build.
• A physical Apple Silicon Mac passed release-artifact checksum verification,
  interactive fresh install, discovery of separate and shared Claude/Codex
  projects, default import, collision-safe aliases, and idempotent re-import.
• The same Mac updated a loaded v0.1.3 installation to this candidate without
  restarting services. Its boot identity, shpool daemon PID, attached shpool
  client PID, and LaunchAgent generations were unchanged; session-kit doctor
  passed afterward.
• Physical device versions: macOS 26.5.1 build 25F80, arm64, shpool 0.11.0,
  Claude Code 2.1.220, Codex CLI 0.146.0, Python 3.14.6, and GNU Bash 5.3.15.
• Native CI covered both supported Mac architectures; physical-device acceptance
  covered Apple Silicon.
• Two independent artifact builds produced byte-identical archive, checksum,
  and provenance files. Archive SHA-256:
  dca76e84469e738632bbc2c636823d97d39c1ccf4f59333143d889f167facba4.

The private source commit is 241b7f25eeee490590dbdb9e005fdc8cb1b3c792.
The public release commit is 05cc2e9e8652d7a4364a5ba71408b6a2bef0fe46.

Session Kit v0.1.3 (Public Beta)

Session Kit v0.1.3

This public beta patch fixes guarded session actions after a Claude process enters the Darwin exiting state.

Fixed

• Ignored stale Claude agent records whose PID no longer has a live process generation.
• Prevented a terminated provider record from blocking later exact close, attach, takeover, prune, or repair actions on macOS.
• Kept live outside-provider sessions visible when their PID and process generation are both available.

Verification

• The private source passed 397 tests. The exact sanitized public export passed 395 tests plus ShellCheck, Ruff, bytecode, documentation, privacy, reachable-history, and reproducible-build gates.
• GitHub Actions run 30860689805 passed all 12 jobs, including native macOS arm64 and x86_64 jobs and Ubuntu 22.04 and 24.04 with Python 3.10 through 3.13.
• A physical Apple Silicon Mac reproduced the stale exiting process, installed the candidate without restarting shpool, restored live guarded inventory, and then closed both remaining exact disposable sessions. The original named session remained untouched.
• Physical device versions: macOS 26.5.1 build 25F80, arm64, shpool 0.11.0, Claude Code 2.1.220, Codex CLI 0.146.0, Python 3.14.6, and GNU Bash 5.3.15.
• Two independent artifact builds produced byte-identical archive, checksum, and provenance files. Archive SHA-256: f299ffcc9f282c0013bf04ebdc679e95b068818748dcccbca0952afb31c06393.

The private source commit is bfca18d5f474bf28568288ecf65312929679cb8b. The public release commit is bb07315.

Session Kit v0.1.2 (Public Beta)

Session Kit v0.1.2

This public beta patch fixes BSD mktemp compatibility across macOS lifecycle paths.

Fixed

• Moved runtime filename suffixes before the replacement characters so BSD and GNU mktemp both create unique files.
• Restored macOS open, takeover, close, prune, reaper, watchdog, login, snapshot, and provider-proof operations that could collide with a literal XXXXXX filename.
• Added a repository-wide regression that rejects nonportable runtime mktemp templates.

Verification

• The private source passed 396 tests. The exact sanitized public export passed 394 tests plus ShellCheck, Ruff, bytecode, documentation, privacy, reachable-history, and reproducible-build gates.
• GitHub Actions run 30859692587 passed all 12 jobs, including native macOS arm64 and x86_64 jobs and Ubuntu 22.04 and 24.04 with Python 3.10 through 3.13.
• A physical Apple Silicon Mac passed install preflight, update, doctor, exact session attach, detach, and a fresh Claude launch with the native green color visible before the first user prompt. The update preserved shpool PID 82081 and all loaded LaunchAgents.
• Physical device versions: macOS 26.5.1 build 25F80, arm64, shpool 0.11.0, Claude Code 2.1.220, Codex CLI 0.146.0, Python 3.14.6, and GNU Bash 5.3.15.
• Two independent artifact builds produced byte-identical archive, checksum, and provenance files. Archive SHA-256: 76fe85d542e91826ba50d88dc44bf6464e64206cb74f0c18d4c62989122c467d.

The private source commit is 5b7ef6ff4f17e08a31a420233cea218bf2005bbd. The public release commit is b281a91.

Session Kit v0.1.1 (Public Beta)

Session Kit v0.1.1\n\nThis public beta patch fixes Claude Code title and color hydration on Linux and macOS.\n\n## Fixed\n\n- Preserved pipeline input through the cross-platform timeout wrapper so the hidden Claude bootstrap receives its native color command.\n- Reconciled a Claude transcript auto-title into the provider native name record without replacing an explicit rename.\n- Passed the stored title through Claude native name option when an exited provider is reopened.\n- Kept the dashboard title state pending until the live Claude generation reports the same name.\n\n## Verification\n\n- The private source passed 395 tests. The exact sanitized public export passed 393 tests plus privacy, reachable-history, documentation, lint, type, coverage, and reproducible-build gates.\n- GitHub Actions run 30854835176 passed all 12 jobs across Ubuntu 22.04 and 24.04, Python 3.10 through 3.13, macOS 15 Apple Silicon, and macOS 15 Intel.\n- Both native macOS jobs explicitly ran the new timeout, Claude hydration, manual-choice protection, and exact name-on-reopen regressions.\n- Two independent artifact builds produced byte-identical archive, checksum, and provenance files. Archive SHA-256: fbbf8c172f660dae05c9c328e63e90667222de3f3c2623021af4270325cef6dc.\n\n## Provider behavior\n\nA process cannot externally repaint an already-running Claude TUI. Session Kit prepares the native title and color records, reports title pending while the current generation is stale, and applies the stored title on the next exact start or normal reopen. New Claude sessions bootstrap the stable color before their first visible frame.\n\nThe private source commit is 3a843fb4053cb13db589fb324194d5ed4d8e0d4d. The public release commit is 24c0698.

Session Kit v0.1.0 (Public Beta)

Session Kit v0.1.0

This is the first public beta of Session Kit for Linux with systemd and macOS
14 or newer.

Session Kit keeps shpool terminals available across SSH disconnects and provider
exits. Its picker shows Claude Code, Codex, and shell sessions with stable
numbers, task names, colors, reply state, and exact local identity checks.

Highlights

• On-demand SSH picker with guarded open, move, close, repair, recovery, resume,
  and fork actions.
• Native Linux and macOS process identity with changed-generation refusal.
• Exact Claude Code and Codex conversation binding.
• Per-user systemd and launchd lifecycle commands.
• Immutable local releases with update and rollback that do not restart shpool.
• Optional terminal journals, off by default.
• Report-only watchdog by default. Automated watchdog repair remains Linux-only.
• No account, hosted service, analytics, update beacon, or telemetry.

Release evidence

• The local release gate passed 391 tests plus ShellCheck, Ruff, formatting,
  Python compilation, mypy, documentation links, privacy scanning, exact public
  export, checksum verification, and two byte-identical artifact builds.
• Real-device acceptance passed on macOS 26.5.1 build 25F80 on Apple Silicon
  with Bash 5.3.15, Python 3.14.6, shpool 0.11.0, Claude Code 2.1.220, and Codex
  0.146.0. It covered launchd enable and safe-disable refusal, SSH detach and
  reconnect, exact Claude and Codex identity, naming, colors, provider exit,
  journals on and off, reaper, prune, report-only watchdog, update, rollback,
  and final update without restarting shpool.
• GitHub CI covers Ubuntu 22.04 and 24.04 with Python 3.10 through 3.13, plus
  native macOS 15 Apple Silicon and Intel runners. Intel coverage is native CI,
  not real-provider device acceptance for this beta.

macOS services require the same user to be logged into the Mac desktop so the
per-user GUI LaunchAgent domain exists. A privileged or pre-login LaunchDaemon
is not included.

Install

Download the archive, checksum, and provenance files below. Verify the checksum,
then follow the README. The archive is generated from private source commit
f90dfb917e32b038c795fcee2b04be050abdeb8e; the public release commit is
6acebd72cbba5ed1f6aba200bbb90a3c11e40368.

Stable v1.0.0 is not part of this publication. It can be considered after the
seven-day beta evidence gate completes with no safety, data-loss, install,
update, or rollback blocker.