feat: handoff / inbox / ack subcommands for structured cross-session work transfer

Adds three new subcommands and a SQLite handoffs table for tracking
work passed between sessions (or future-you).

New commands:
- handoff: write a brief with optional structured notes
  (--done / --pending / --blocked), log to handoffs table,
  optionally launch the target session immediately. Supports
  --target-cli, --target-cwd, --target-session, --require-ack.
- inbox: show pending handoffs whose target_cli, target_cwd
  prefix, or target_session_id matches the current context
  (defaults to env-detected source, $PWD, and CLAUDE_CODE_SESSION_ID).
- ack <id>: mark a handoff as absorbed; records ack_at,
  ack_session_id, optional --note.

Brief writer: gained an optional notes parameter that prepends
a "## Handoff Notes" section (What's done / What's pending /
What's blocked) before the existing transcript-derived content.
Backward compatible - existing brief callers pass nothing.

Schema: new handoffs table with indexes on target_cwd,
target_session_id, and status. Idempotent CREATE IF NOT EXISTS
so existing installs pick up the table on next invocation.

UX: /absorb action menu surfaces handoff via the More submenu;
all three commands are pass-through subcommands for /absorb.

Tests: 10 new pytest smoke tests covering help, dry-run,
empty-inbox, env-aware session resolution, and error paths.
All 18 tests passing on Python 3.12+.

Docs: README, reference, use-cases, CHANGELOG, and all three
SKILL.md files updated with command listings, examples, and
two new use-case scenarios (end-of-day async handoff,
cross-CLI handoff with require-ack).

Author: ThatGuyAstro

CHANGELOG.md

@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- `handoff` subcommand for structured cross-session work transfer with optional note fields (`--done`, `--pending`, `--blocked`) and acknowledgment tracking.
+- `inbox` subcommand to show pending handoffs targeted at the current cwd, CLI, or session id.
+- `ack` subcommand to mark a handoff as absorbed by the receiving session.
+- New `handoffs` SQLite table at `~/.local/share/session-absorb/sessions.db` for handoff state tracking.
+- Brief writer now prepends a `## Handoff Notes` section (What's done / What's pending / What's blocked) when handoff notes are supplied.
+
 ## [0.1.0] - 2026-05-08
 
 ### Added

README.md

@@ -40,6 +40,15 @@ In the picker, choose the Codex session. Then "Handoff to other CLI". A brief ge
 
 New Terminal window, new Claude session, same context. The session you're in now keeps going untouched.
 
+**End of the day, hand off to tomorrow.** You shipped half a PR. You won't remember the state by morning. Write a handoff for the next session that opens in this directory.
+
+```
+session-absorb handoff --no-launch --target-cwd "$(pwd)" \
+    --done "API routes done" --pending "frontend wiring" --blocked "Stripe key"
+```
+
+Tomorrow's session runs `/absorb inbox`, sees the pending handoff, reads the brief, picks up where you stopped.
+
 ## Install
 
 ```bash
@@ -93,14 +102,16 @@ For handoff, same-platform transfers prefer native forks: `claude -r <session> -
 
 ## Commands
 
-The shared CLI exposes twelve subcommands. The ones you'll touch directly:
+The shared CLI exposes the subcommands you'll touch directly:
 
 **Find a session:** `list` (interactive picker or table), `init` (assign or override an alias code), `pick` (select by number from the last chat menu).
 
 **Do something with it:** `digest`, `ask --question`, `brief`, `launch` (native fork or cross-platform handoff).
 
 **Shortcuts:** `here [action]` for the cwd default, `last [action]` for anywhere, `fork-myself` for the current session.
 
+**Handoff:** `handoff` (write a brief and log it for the next session), `inbox` (list pending handoffs aimed at you), `ack` (mark one absorbed).
+
 **Plumbing:** `db` to inspect the SQLite catalog, `web` to serve a local live dashboard, `install` to (re)install the runtime and skills.
 
 Visual cues distinguish the two CLIs everywhere: `🟠` for Claude and `🟢` for Codex in the in-chat picker, `◆C` and `◇X` in plain text, ANSI 214 (orange) and 51 (cyan) in real terminals. Honors `NO_COLOR` and `FORCE_COLOR`.

docs/reference.md

@@ -249,6 +249,83 @@ session-absorb last brief --question "Absorb everything from this morning"
 session-absorb last show
 ```
 
+## `session-absorb handoff`
+
+_Reach for this when: you're done with this work and someone else (or future-you, in another session) needs to pick it up._
+
+Writes a bridge brief, optionally launches the target CLI, and logs a row to the inbox so the receiving session can find it. When any of `--done`, `--pending`, or `--blocked` is supplied, the brief gets a `## Handoff Notes` section at the top with those fields.
+
+Flags:
+
+- `--source {claude,codex}` - source CLI (defaults to env: `CLAUDE_CODE_SESSION_ID` / `CODEX_SESSION_ID`)
+- `--session <selector>` - source session (defaults to current session)
+- `--target-cli {claude,codex}` - which CLI should pick this up (defaults to source CLI)
+- `--target-cwd <path>` - cwd-prefix filter for inbox match
+- `--target-session <selector>` - exact target session id or alias
+- `--done <text>` - what's done
+- `--pending <text>` - what's pending
+- `--blocked <text>` - what's blocked
+- `--launch / --no-launch` - immediate target launch (default: True if cross-CLI or `--target-session` given)
+- `--require-ack` - flag the handoff as needing acknowledgment
+- `--question <text>` - focus question for the brief
+- `--workspace <path>` - brief output workspace
+- `--limit <n>` - excerpt limit (default: `8`)
+- `--dry-run` - print the launch command without executing
+
+Examples:
+
+```bash
+# Same-CLI handoff to a fresh fork, with a structured note
+session-absorb handoff --done "auth refactor merged" --pending "tests for /login" --blocked "needs DB migration review"
+
+# Cross-CLI handoff: from Codex to Claude, immediate launch
+session-absorb handoff --target-cli claude --done "stripe webhooks wired up"
+
+# Async handoff: write the brief and log it, don't launch (someone else picks it up)
+session-absorb handoff --no-launch --target-cwd ~/proj/api --pending "wire up rate limits" --require-ack
+```
+
+## `session-absorb inbox`
+
+_Reach for this when: you're starting a session and want to know if anything was handed off to you._
+
+Lists pending handoffs targeted at the current session. By default, matches against your CLI, your cwd (prefix), and your session id. A handoff matches when each of `target_cli`, `target_cwd`, and `target_session_id` is either null or matches you. Acked or expired handoffs are excluded unless `--show-all` is set.
+
+Flags:
+
+- `--source {claude,codex,all}` - filter target_cli (default: env, fallback `all`)
+- `--cwd <path>` - cwd to match against (default: `$PWD`)
+- `--show-all` - include acked and expired handoffs
+- `--json` - print JSON instead of a table
+- `--limit <n>` - max rows to display
+
+Examples:
+
+```bash
+session-absorb inbox
+session-absorb inbox --json
+session-absorb inbox --show-all
+session-absorb inbox --cwd ~/proj/api
+```
+
+## `session-absorb ack <handoff-id>`
+
+_Reach for this when: you've absorbed a handoff and want the source session to know it landed._
+
+Marks a handoff as acknowledged. The source session can then see the ack via `session-absorb inbox --show-all`.
+
+Flags:
+
+- positional `<handoff-id>` - row id from `inbox` output (required)
+- `--note <text>` - optional note attached to the ack
+
+Examples:
+
+```bash
+session-absorb ack 3
+session-absorb ack 3 --note "picked it up, continuing now"
+```
+
 ## `session-absorb fork-myself`
 
 _Reach for this when: you're about to try something risky and want a parallel session that inherits everything._
@@ -330,6 +407,8 @@ Source differentiation stays consistent across every output surface:
 | `/absorb` AskUserQuestion picker | `🟠` orange circle | `🟢` green circle | Plus `📋` for the manual-pick escape option |
 | Self marker | `*self*` suffix in plain output, `is_current: true` in JSON | same | Matched against `CLAUDE_CODE_SESSION_ID` / `CODEX_SESSION_ID` env vars |
 
+`inbox` output uses the same source-color encoding as `list`: orange for Claude, cyan for Codex in TTY, `🟠` / `🟢` in chat menus, `◆C` / `◇X` in plain text.
+
 ## Environment variables
 
 - `CLAUDE_CODE_SESSION_ID` - exported by Claude Code into subprocess env. When present and matching a session's `session_id`, that record is flagged `is_current: true` in JSON output and annotated `*self*` in plain output.
@@ -348,6 +427,9 @@ Lives at `skills/claude/absorb/SKILL.md` (alias of `/session-absorb`). Routes by
 | `/absorb last [action]` | B | Pass-through to `session-absorb last`. Default action `digest`. |
 | `/absorb pick` | B | Forces the multi-step click picker. |
 | `/absorb fork-myself` | B | Pass-through to `session-absorb fork-myself`. Forks your current active session. |
+| `/absorb handoff [args]` | C | Pass-through to `session-absorb handoff`. Writes a brief, logs to inbox, optionally launches target. |
+| `/absorb inbox [args]` | C | Pass-through to `session-absorb inbox`. Shows pending handoffs targeted at this session. |
+| `/absorb ack <id> [--note <text>]` | C | Pass-through to `session-absorb ack`. Marks a handoff absorbed. |
 | `/absorb <subcommand> [args]` | C | Direct pass-through to `session-absorb`. |
 | `/absorb <free text>` | D | Haiku subagent resolves intent (session match + verb) and runs the command in one shot. |
 

docs/use-cases.md

@@ -36,7 +36,27 @@ You used Codex CLI to scaffold a new module because its planner felt right for t
 
 Pick the Codex session (it's the green circle in the picker), choose `🤝 Handoff to other CLI`. A bridge brief gets written to `.session-absorb/briefs/`. A fresh Claude Code window opens in a new Terminal, primed with the brief as its first user message. The receiving session knows what tools were used, what files were touched, and what the previous CLI was trying to accomplish. Codex has no non-interactive fork API, so brief-driven handoff is the right road for cross-CLI work, not a fallback.
 
-**4. One question, not a whole digest**
+**4. Hand work to your future self in 8 hours**
+
+End of the day, you've got one PR half-done. You won't remember the state by morning. You write a structured handoff to whichever Claude session opens in this cwd next.
+
+```
+session-absorb handoff --no-launch --target-cwd "$(pwd)" --done "API routes wired" --pending "frontend integration" --blocked "waiting on Stripe API key"
+```
+
+Tomorrow you start a Claude session in the same directory and run `/absorb inbox`. The pending handoff shows up. You read the brief and pick up exactly where you stopped.
+
+**5. Cross-CLI handoff with explicit ack**
+
+You ran a heavy refactor in Codex. You want Claude to take over. You also want to know whether Claude actually started.
+
+```
+session-absorb handoff --target-cli claude --require-ack --done "refactor complete, all tests passing" --pending "performance benchmarks"
+```
+
+Claude session opens. After it absorbs the brief, it runs `session-absorb ack <id>`. Your Codex session can check `session-absorb inbox --show-all` to confirm the handoff was acknowledged.
+
+**6. One question, not a whole digest**
 
 You remember a session figured out a specific thing. Whether you wired up Stripe webhooks, what port the mock server ran on, why the migration kept failing. You don't want a 600-line digest, you want one answer.
 
@@ -52,7 +72,7 @@ Pick the session, choose `🎯 More`, then `🔎 Ask question`. Or skip the menu
 
 For Claude sessions, `--live auto` tries a real forked query first. If that fails (sometimes resumed sessions choke on stale tool markers), you fall back to a ranked transcript-backed answer pack. Either way you get something usable.
 
-**5. Try something risky without losing your place**
+**7. Try something risky without losing your place**
 
 You're 40 messages deep in a session that's working. You want to try a refactor that might blow it up. You don't want to stash, branch, and lose your seat in the chat.
 
@@ -62,7 +82,7 @@ You're 40 messages deep in a session that's working. You want to try a refactor
 
 A new Terminal window opens with a parallel Claude Code session that inherits everything up to right now. The original keeps running in your current window, untouched. Use the fork to experiment with the refactor. If it works, merge the diffs back manually. If it doesn't, close the window and pretend it never happened. Same-CLI native fork only, no brief involved. Reads `CLAUDE_CODE_SESSION_ID` from your env to know who "myself" is.
 
-**6. Hand the work to a teammate**
+**8. Hand the work to a teammate**
 
 Sometimes a teammate needs to pick up where you left off and they don't have your terminal. You need a written artifact, not a fork.
 
@@ -72,7 +92,7 @@ Sometimes a teammate needs to pick up where you left off and they don't have you
 
 Pick the session, choose `🎯 More`, then `📝 Brief only`. The brief lands at `.session-absorb/briefs/<timestamp>-<source>-<sessionid>.md` (e.g. `20260508T143022Z-claude-abc123.md`). Plain Markdown: metadata, dominant tools, recent turns, ranked excerpts, instructions for the receiving session. Slack it, paste it into a PR description, attach it to a Linear ticket. It's just a file.
 
-**7. You're juggling six sessions and need to see them all**
+**9. You're juggling six sessions and need to see them all**
 
 It's late, you've been hopping between four repos, and you've lost track of which sessions are still warm and which ones you can let go.
 
@@ -82,7 +102,7 @@ It's late, you've been hopping between four repos, and you've lost track of whic
 
 A flat table of every session updated in the last 240 minutes. Claude rows render in orange (ANSI 214), Codex rows in cyan (ANSI 51). Your current session gets a `*self*` annotation in plain output so you don't waste a beat trying to digest yourself. `--active-only` clamps the list to live work, not yesterday's archaeological record. Honors `NO_COLOR` and `FORCE_COLOR` if you pipe it.
 
-**8. You want to give one a name so you stop typing UUIDs**
+**10. You want to give one a name so you stop typing UUIDs**
 
 There's a session you keep coming back to. The big dashboard refactor, the one with all the open threads. Typing `4f3a8b21-...` every time is friction.
 

skills/claude/absorb/SKILL.md

@@ -14,7 +14,7 @@ Classify `{{ARGUMENTS}}` and pick a path:
 
 1. No args → **Path A: cwd auto-default** (most common, 1-click)
 2. First arg is `pick` / `here` / `last` → **Path B: shortcut**
-3. First arg is `list|pick|init|digest|ask|brief|launch|here|last|fork-myself|db|web|install` → **Path C: pass-through**
+3. First arg is `list|pick|init|digest|ask|brief|launch|here|last|fork-myself|handoff|inbox|ack|db|web|install` → **Path C: pass-through**
 4. Free text → **Path D: Haiku natural-language dispatch**
 
 ## Path A: bare `/absorb` (cwd auto-default)
@@ -72,14 +72,14 @@ For 🎯 More, render a follow-up AskUserQuestion:
 > Options (max 4):
 > 1. `🔎 Ask question` — description: `Ask a targeted question (uses default text).`
 > 2. `📝 Brief only` — description: `Write a bridge brief to .session-absorb/briefs/ without launching.`
-> 3. `🪞 Fork myself` — description: `Fork the CURRENT session (not the picked one) into a new Terminal.`
+> 3. `📦 Handoff` - description: `Hand this session off with a structured note for the next picker-up.`
 > 4. `↩️ Back`
 
 | Secondary | Command |
 |---|---|
 | 🔎 Ask question | `$HOME/.local/bin/session-absorb ask --source <s> --session <c> --question "<default ask text>"` |
 | 📝 Brief only | `$HOME/.local/bin/session-absorb brief --source <s> --session <c> --question "<default brief text>"` |
-| 🪞 Fork myself | `$HOME/.local/bin/session-absorb fork-myself` (ignores the picked session entirely - forks the user's CURRENT active session via `CLAUDE_CODE_SESSION_ID`) |
+| 📦 Handoff | `$HOME/.local/bin/session-absorb handoff --source <s> --session <c>` (plus any `--done`/`--pending`/`--blocked` text the user provides; runs against the picked session as source) |
 | ↩️ Back | re-render Step 3 |
 
 ### Default questions (do NOT prompt)
@@ -153,6 +153,16 @@ AskUserQuestion option labels (chat-rendered, color via emoji):
 
 Plain-text contexts (chat menu, terminal, curses): `◆C` (Claude) / `◇X` (Codex) — runtime emits these automatically.
 
+## Inbox check on session start
+
+When `/absorb` is invoked with no args (Path A), before rendering the action picker, run:
+
+```bash
+$HOME/.local/bin/session-absorb inbox --json --limit 5
+```
+
+If the result is non-empty (pending handoffs targeted at this cwd, CLI, or session id), surface a 1-line summary at the top of the response - "📦 N pending handoff(s) for this session" - and offer to absorb the most recent one before continuing with the normal Path A flow. The user can then run `/absorb ack <id>` after they've digested it.
+
 ## Important constraints
 
 - Never invoke yourself: runtime filters `is_current` sessions. Don't override.

skills/claude/session-absorb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: session-absorb
 description: Use when you need to absorb, merge, or consult context from another Claude Code or Codex session without copy-pasting, including native Claude fork launch, Codex fork launch, transcript-backed bridge briefs, and focused session Q and A.
-argument-hint: "<list|pick|init|digest|ask|brief|launch|db|web|install> [args]"
+argument-hint: "<list|pick|init|digest|ask|brief|launch|handoff|inbox|ack|db|web|install> [args]"
 ---
 
 # Session Absorb
@@ -21,6 +21,9 @@ Canonical slash command: `/session-absorb`
 | `ask` | query a session or build ranked excerpts | `/session-absorb ask --source codex --session <id> --question "What changed?"` |
 | `brief` | write a bridge brief | `/session-absorb brief --source claude --session <id> --question "Absorb and continue"` |
 | `launch` | open a native fork or bridge session in Terminal | `/session-absorb launch --source codex --session <id> --target claude` |
+| `handoff` | write a brief, log it for the next session, optionally launch the target | `/session-absorb handoff --done "auth merged" --pending "tests"` |
+| `inbox` | list pending handoffs targeted at this session, cwd, or CLI | `/session-absorb inbox` |
+| `ack` | mark a handoff absorbed (referenced by id from `inbox`) | `/session-absorb ack 3 --note "picked it up"` |
 | `db` | inspect the SQLite session catalog and active-state counts | `/session-absorb db` |
 | `web` | serve the live local dashboard for sessions and states | `/session-absorb web --open-browser` |
 | `install` | install the runtime and skill wrappers into both home registries | `/session-absorb install --repo-root <repo-root>` |
@@ -96,7 +99,27 @@ session-absorb launch --source claude --session DASH1 --mode native
 ```bash
 session-absorb launch --source codex --session OPS42 --target claude --question "Absorb the implementation context and continue from there."
 
-7. Open the live dashboard:
+7. Hand off to the next session, then ack from the receiving side:
+
+In the source session (end of day, work half-done):
+
+```bash
+session-absorb handoff --no-launch --target-cwd "$(pwd)" --done "API routes wired" --pending "frontend integration" --blocked "Stripe key"
+```
+
+Next morning, in a fresh session in the same directory:
+
+```bash
+session-absorb inbox
+```
+
+After reading the brief, mark it absorbed:
+
+```bash
+session-absorb ack 3 --note "picked it up, continuing now"
+```
+
+8. Open the live dashboard:
 
 ```bash
 session-absorb web --open-browser

skills/codex/session-absorb/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: session-absorb
 description: Use when you need to absorb, merge, or consult context from another Codex or Claude Code session without copy-pasting, including native fork launch for same-CLI sessions and transcript-backed bridge briefs across CLIs.
-argument-hint: "<list|pick|init|digest|ask|brief|launch|db|web|install> [args]"
+argument-hint: "<list|pick|init|digest|ask|brief|launch|handoff|inbox|ack|db|web|install> [args]"
 ---
 
 # Session Absorb
@@ -21,6 +21,9 @@ Canonical command surface: `session-absorb <subcommand> ...`
 | `ask` | extract an answer or ranked excerpts | `session-absorb ask --source codex --session <id> --question "What changed?"` |
 | `brief` | write a bridge brief for another session | `session-absorb brief --source claude --session <id> --question "Absorb and continue"` |
 | `launch` | open a native fork or brief-driven bridge in Terminal | `session-absorb launch --source claude --session <id> --target codex` |
+| `handoff` | write a brief, log it for the next session, optionally launch the target | `session-absorb handoff --done "refactor done" --pending "benchmarks"` |
+| `inbox` | list pending handoffs targeted at this session, cwd, or CLI | `session-absorb inbox` |
+| `ack` | mark a handoff absorbed (referenced by id from `inbox`) | `session-absorb ack 3 --note "got it"` |
 | `db` | inspect the SQLite session catalog and active-state counts | `session-absorb db` |
 | `web` | serve the live local dashboard for sessions and states | `session-absorb web --open-browser` |
 | `install` | install the runtime and skill wrappers into your home directories | `session-absorb install --repo-root <repo-root>` |
@@ -115,6 +118,18 @@ Launch a cross-CLI bridge session from a brief:
 ```bash
 session-absorb launch --source claude --session <session-id> --target codex --question "Absorb the design work and continue implementation."
 
+Cross-CLI handoff with explicit ack. From Codex, push to a fresh Claude session and require ack:
+
+```bash
+session-absorb handoff --target-cli claude --require-ack --done "refactor complete" --pending "performance benchmarks"
+```
+
+Later, check whether Claude actually absorbed it:
+
+```bash
+session-absorb inbox --show-all
+```
+
 Open the live dashboard:
 
 ```bash