@tekmidian/pai 0.15.0 → 0.17.0

package/docs/commands/session.md

@@ -0,0 +1,295 @@
+<!-- GENERATED by scripts/build-docs.mjs from the live Commander tree (src/cli/program.ts). Do not edit by hand. -->
+
+# pai session
+
+> Session management: list, info, checkpoint, handover, cleanup, slug, tag, route.
+
+Short forms: `pai pause`, `pai end`, `pai resume <name>`.
+
+## Synopsis
+
+```
+pai session <subcommand> [options]
+```
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [`pai session list`](#pai-session-list) | Resumable sessions catalog — named sessions with resume status. |
+| [`pai session info <project-slug> <number>`](#pai-session-info-project-slug-number) | Show full details for a specific session |
+| [`pai session rename <project-slug> <number> <new-slug>`](#pai-session-rename-project-slug-number-new-slug) | Rename a session note — updates file on disk, H1 title, and registry |
+| [`pai session slug <project-slug> <number>`](#pai-session-slug-project-slug-number) | Generate a descriptive slug from the session JSONL transcript |
+| [`pai session tag <project-slug> <number> [tags...]`](#pai-session-tag-project-slug-number-tags) | Set or show tags on a session. Tags can be space-separated or comma-separated. |
+| [`pai session route <project-slug> <number> <target-project>`](#pai-session-route-project-slug-number-target-project) | Create a cross-reference link from a session to a target project |
+| [`pai session handover [project-slug] [number-or-latest]`](#pai-session-handover-project-slug-number-or-latest) | Write a ## Continue section to the project's TODO.md. |
+| [`pai session checkpoint <message>`](#pai-session-checkpoint-message) | Append a timestamped checkpoint to the active session note. |
+| [`pai session autosave`](#pai-session-autosave) | Refresh the ## Continue checkpoint from the transcript and working tree. |
+| [`pai session active`](#pai-session-active) | Show currently active Claude Code sessions. |
+| [`pai session recent`](#pai-session-recent) | [Deprecated] Use `pai session list` or `pai sessions` instead. |
+| [`pai session goto <name-or-id>`](#pai-session-goto-name-or-id) | Go to a session: resume if a resumable snapshot exists, start fresh otherwise. |
+| [`pai session pause`](#pai-session-pause) | Write a ## Continue checkpoint to the project's TODO.md. |
+| [`pai session auto-route`](#pai-session-auto-route) | Auto-detect which project this session belongs to. |
+| [`pai session cleanup [project-slug]`](#pai-session-cleanup-project-slug) | Clean up session notes: delete empties, auto-name unnamed, move into YYYY/MM/ hierarchy, renumber |
+
+### pai session list
+
+Resumable sessions catalog — named sessions with resume status.
+
+Short form: pai sessions
+Default shows all sessions you've named or that are resumable.
+Use --all to also show unnamed orphan sessions.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n <count>` | Maximum sessions to show (default: 20) | `20` |
+| `--all` | Include unnamed orphan sessions (not in clc registry) |  |
+| `--json` | Output raw JSON instead of formatted table |  |
+
+
+### pai session info <project-slug> <number>
+
+Show full details for a specific session
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<project-slug>` | required |
+| `<number>` | required |
+
+
+### pai session rename <project-slug> <number> <new-slug>
+
+Rename a session note — updates file on disk, H1 title, and registry
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<project-slug>` | required |
+| `<number>` | required |
+| `<new-slug>` | required |
+
+
+### pai session slug <project-slug> <number>
+
+Generate a descriptive slug from the session JSONL transcript
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<project-slug>` | required |
+| `<number>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--apply` | Rename the session note using the generated slug |  |
+
+
+### pai session tag <project-slug> <number> [tags...]
+
+Set or show tags on a session. Tags can be space-separated or comma-separated.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<project-slug>` | required |
+| `<number>` | required |
+| `[tags...]` | variadic |
+
+
+### pai session route <project-slug> <number> <target-project>
+
+Create a cross-reference link from a session to a target project
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<project-slug>` | required |
+| `<number>` | required |
+| `<target-project>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--type <type>` | Link type: related \| follow-up \| reference | `related` |
+
+
+### pai session handover [project-slug] [number-or-latest]
+
+Write a ## Continue section to the project's TODO.md.
+
+Called automatically from session-stop and pre-compact hooks.
+Records the last session identifier, timestamp, and working directory
+so the next session can resume from the correct context.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `[project-slug]` | optional |
+| `[number-or-latest]` | optional |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--session-id <uuid>` | Claude session UUID. Used to decide whether an existing authored checkpoint belongs to this session and must be preserved. Without it the comparison falls back to the session note filename, which the stop hook itself renames — so pass it whenever it is known. |  |
+
+
+### pai session checkpoint <message>
+
+Append a timestamped checkpoint to the active session note.
+
+Designed for hooks (PostToolUse, UserPromptSubmit) — fast and silent.
+Rate-limited: skips silently if last checkpoint was < --min-gap seconds ago.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<message>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--min-gap <seconds>` | Minimum seconds between checkpoints (default: 300 = 5 minutes) | `300` |
+
+
+### pai session autosave
+
+Refresh the ## Continue checkpoint from the transcript and working tree.
+
+Runs unattended from live hooks so an interrupted session still leaves
+a usable handover. Writes in auto mode, so a model-authored checkpoint
+for the same session is preserved untouched. Silent; always exits 0.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--session-id <uuid>` | Claude session UUID — the key that decides whether an existing authored checkpoint belongs to this session and must be left alone. |  |
+| `--min-gap <seconds>` | Minimum seconds between autosaves, shared across all triggers (default: 240) | `240` |
+| `--dry-run` | Print the block that would be written and exit |  |
+
+
+### pai session active
+
+Show currently active Claude Code sessions.
+
+Detects live sessions by checking which JSONL transcript files
+were recently modified in ~/.claude/projects/.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--minutes <n>` | Consider sessions active if modified within N minutes (default: 60) | `60` |
+| `--json` | Output raw JSON instead of formatted display |  |
+
+
+### pai session recent
+
+[Deprecated] Use `pai session list` or `pai sessions` instead.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-n <count>` | Maximum sessions to show (default: 20) | `20` |
+| `--all` | Include unnamed orphan sessions (not in clc registry) |  |
+| `--json` | Output raw JSON instead of formatted table |  |
+
+
+### pai session goto <name-or-id>
+
+Go to a session: resume if a resumable snapshot exists, start fresh otherwise.
+
+Recommended short form: pai resume <name>
+Resolves by clc/registry name (case-insensitive) or UUID prefix.
+Sends '/Name <name>\ngo' as the initial prompt so the PAI ## Continue hook fires.
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `<name-or-id>` | required |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--skip-name` | Do not prepend /Name to set the session name in chrome |  |
+| `--skip-go` | Do not append \ngo to trigger PAI auto-resume (## Continue) |  |
+| `--dry-run` | Print the exact argv and cwd, then exit without launching |  |
+
+
+### pai session pause
+
+Write a ## Continue checkpoint to the project's TODO.md.
+
+Recommended short form: pai pause
+Ctrl+C bypasses the stop-hook, orphaning the session (cannot --resume).
+Use /exit inside Claude Code to preserve full session resumability.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--dry-run` | Preview the ## Continue block without writing it |  |
+| `--body-file <path>` | File holding the checkpoint markdown to persist ('-' reads stdin). Required unless --no-body. |  |
+| `--session-id <uuid>` | Claude Code session UUID — recorded as the `claude --resume` handle |  |
+| `--no-body` | Deliberately write a metadata-only checkpoint (no content) |  |
+
+
+### pai session auto-route
+
+Auto-detect which project this session belongs to.
+
+Tries: (1) path match in registry, (2) Notes/PAI.md marker walk, (3) topic detection.
+Designed for use in CLAUDE.md session-start hooks.
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--cwd <path>` | Working directory to detect from (default: process.cwd()) |  |
+| `--context <text>` | Conversation context for topic-based fallback routing |  |
+| `--json` | Output raw JSON instead of formatted display |  |
+
+
+### pai session cleanup [project-slug]
+
+Clean up session notes: delete empties, auto-name unnamed, move into YYYY/MM/ hierarchy, renumber
+
+**Arguments**
+
+| Argument | Kind |
+|----------|------|
+| `[project-slug]` | optional |
+
+**Options**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--execute` | Actually perform the cleanup (default is dry-run) |  |
+| `--no-renumber` | Skip renumbering sessions after deletions |  |
+| `--no-reindex` | Skip triggering memory re-index after moves |  |
+
+
+## See also
+
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+
+Run `pai help <area>` to read any of these in the terminal.
+

package/docs/commands/sessions.md

@@ -19,7 +19,7 @@ pai sessions [options]
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/setup.md

@@ -14,7 +14,7 @@ pai setup
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/shell-init.md

@@ -12,7 +12,7 @@ pai shell-init
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/skill.md

@@ -48,7 +48,7 @@ See `Notes/swarm/skills-self-educating.md` for the full self-educating loop
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/task.md

@@ -142,7 +142,7 @@ Mark a task complete on the tracker
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai topic`](topic.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/topic.md

@@ -40,7 +40,7 @@ Exit code 1 if a shift is detected (useful for hooks).
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai update`](update.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/update.md

@@ -12,7 +12,7 @@ pai update
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai zettel`](zettel.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai zettel`](zettel.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/docs/commands/zettel.md

@@ -145,7 +145,7 @@ pai zettel health
 
 ## See also
 
-[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md)
+[`pai backup`](backup.md) · [`pai clear-names`](clear-names.md) · [`pai daemon`](daemon.md) · [`pai db`](db.md) · [`pai end`](end.md) · [`pai help`](help.md) · [`pai kg`](kg.md) · [`pai mcp`](mcp.md) · [`pai memory`](memory.md) · [`pai notify`](notify.md) · [`pai observation`](observation.md) · [`pai obsidian`](obsidian.md) · [`pai pause`](pause.md) · [`pai project`](project.md) · [`pai projects`](projects.md) · [`pai registry`](registry.md) · [`pai restore`](restore.md) · [`pai session`](session.md) · [`pai sessions`](sessions.md) · [`pai setup`](setup.md) · [`pai shell-init`](shell-init.md) · [`pai skill`](skill.md) · [`pai task`](task.md) · [`pai topic`](topic.md) · [`pai update`](update.md)
 
 Run `pai help <area>` to read any of these in the terminal.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tekmidian/pai",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "PAI Knowledge OS — Personal AI Infrastructure with federated memory and project management",
   "type": "module",
   "main": "dist/index.mjs",

package/plugins/context-preservation/hooks/hooks.json

@@ -1,7 +1,18 @@
 {
   "module": "context-preservation",
-  "description": "Context compression and relay across compaction cycles",
+  "description": "Context preservation across compaction cycles, restarts, and interrupted sessions",
   "hooks": [
+    {
+      "event": "UserPromptSubmit",
+      "command": "${PAI_DIR}/Hooks/pai-session-autosave.sh",
+      "description": "Refresh the rolling ## Continue checkpoint from the transcript and working tree (rate-limited). Never overwrites a model-authored checkpoint for the same session."
+    },
+    {
+      "event": "PostToolUse",
+      "matcher": "*",
+      "command": "${PAI_DIR}/Hooks/pai-session-autosave.sh",
+      "description": "Same rolling checkpoint, so a long working turn interrupted by Ctrl+C still leaves recoverable state"
+    },
     {
       "event": "PreCompact",
       "command": "${PAI_DIR}/Hooks/context-compression-hook.mjs",

package/scripts/build-hooks.mjs

@@ -24,6 +24,8 @@ import {
   copyFileSync,
   readFileSync,
   writeFileSync,
+  renameSync,
+  rmSync,
 } from "fs";
 import { join, resolve, basename } from "path";
 import { homedir, platform } from "os";
@@ -51,8 +53,24 @@ const entryPoints = collectEntryPoints(HOOKS_SRC);
 
 console.log(`Building ${entryPoints.length} hooks with esbuild...`);
 
+// Build into a staging directory, then rename each artefact into place.
+//
+// ~/.claude/Hooks/*.mjs are symlinks to these files, and every LIVE Claude Code
+// session executes them on each tool call. esbuild truncates-then-writes, so
+// building straight to the output path leaves a window in which the file does
+// not exist — any hook firing during a build in another session dies with
+// "No such file or directory". That is not hypothetical: a rebuild here breaks
+// hooks in every other session that happens to fire during it.
+//
+// rename(2) within one filesystem is atomic, so a concurrent session sees
+// either the previous build or the new one, never a partial or absent file.
+const STAGING = join(HOOKS_OUT, ".staging");
+rmSync(STAGING, { recursive: true, force: true });
+mkdirSync(STAGING, { recursive: true });
+
 for (const entry of entryPoints) {
-  const outfile = join(HOOKS_OUT, basename(entry).replace(/\.ts$/, ".mjs"));
+  const name = basename(entry).replace(/\.ts$/, ".mjs");
+  const staged = join(STAGING, name);
 
   buildSync({
     entryPoints: [entry],
@@ -60,13 +78,24 @@ for (const entry of entryPoints) {
     platform: "node",
     target: "node20",
     format: "esm",
-    outfile,
+    outfile: staged,
     sourcemap: true,
   });
 
-  chmodSync(outfile, 0o755);
+  chmodSync(staged, 0o755);
+
+  // The sourceMappingURL comment is a bare filename, so the map must land in
+  // the same directory as the module. Move it first: a stale map for a moment
+  // is harmless, a missing module is not.
+  const stagedMap = `${staged}.map`;
+  if (existsSync(stagedMap)) {
+    renameSync(stagedMap, join(HOOKS_OUT, `${name}.map`));
+  }
+  renameSync(staged, join(HOOKS_OUT, name));
 }
 
+rmSync(STAGING, { recursive: true, force: true });
+
 console.log(`✔ ${entryPoints.length} hooks built to ${HOOKS_OUT}/`);
 
 // ---------------------------------------------------------------------------
@@ -141,6 +170,7 @@ if (doSync) {
   const shellHooks = [
     ["src/hooks/pre-compact.sh", "pai-pre-compact.sh"],
     ["src/hooks/session-stop.sh", "pai-session-stop.sh"],
+    ["src/hooks/session-autosave.sh", "pai-session-autosave.sh"],
   ];
   for (const [src, destName] of shellHooks) {
     if (existsSync(src)) {

package/src/hooks/session-autosave.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# PAI Knowledge OS — rolling session autosave
+#
+# Fires from live hooks (UserPromptSubmit, PostToolUse) so that a session which
+# never gets a model-authored checkpoint still leaves a usable ## Continue
+# behind. Ctrl+C kills the process without running any stop hook, and /exit does
+# not invoke the model — so an exit-time-only guarantee is no guarantee at all.
+# The state has to be written while the session is still running.
+#
+# Writes in "auto" mode, so a model-authored checkpoint for the same session is
+# preserved untouched. This is the floor, never a replacement for the ceiling.
+#
+# NEVER exits non-zero, NEVER prints — this must not interrupt Claude Code.
+
+PAI_OS="pai"
+command -v "$PAI_OS" &>/dev/null || exit 0
+
+# ---------------------------------------------------------------------------
+# Shell-side rate limit
+# ---------------------------------------------------------------------------
+# PostToolUse fires after every single tool call. The CLI rate-limits too, but
+# reaching it costs a Node start-up each time — hundreds of milliseconds, paid
+# on every tool call in the session. Checking a sentinel's mtime here costs a
+# stat, so the expensive path is only taken when it will actually do work.
+
+MIN_GAP_SECONDS="${PAI_AUTOSAVE_MIN_GAP:-240}"
+
+SENTINEL_KEY=$(printf '%s' "$PWD" | tr -c 'a-zA-Z0-9' '-' | tail -c 80)
+SENTINEL="${TMPDIR:-/tmp}/pai-autosave-hook-${SENTINEL_KEY}"
+
+if [ -f "$SENTINEL" ]; then
+  NOW=$(date +%s)
+  # stat is not portable: BSD/macOS uses -f %m, GNU/Linux uses -c %Y.
+  LAST=$(stat -f %m "$SENTINEL" 2>/dev/null || stat -c %Y "$SENTINEL" 2>/dev/null || echo 0)
+  if [ $((NOW - LAST)) -lt "$MIN_GAP_SECONDS" ]; then
+    exit 0
+  fi
+fi
+
+# ---------------------------------------------------------------------------
+# Session UUID from the hook payload
+# ---------------------------------------------------------------------------
+# The UUID decides whether an existing authored checkpoint belongs to this
+# session and must be left alone. Without it the comparison falls back to the
+# session note filename, which other stop-hook steps rename underneath us.
+
+CLAUDE_SESSION_UUID=""
+if [ ! -t 0 ]; then
+  HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  if [ -n "$HOOK_INPUT" ]; then
+    if command -v jq &>/dev/null; then
+      CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)
+    else
+      CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | python3 -c \
+        "import sys,json; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null || true)
+    fi
+  fi
+fi
+
+touch "$SENTINEL" 2>/dev/null || true
+
+if [ -n "$CLAUDE_SESSION_UUID" ]; then
+  "$PAI_OS" session autosave --session-id "$CLAUDE_SESSION_UUID" \
+    --min-gap "$MIN_GAP_SECONDS" &>/dev/null || true
+else
+  "$PAI_OS" session autosave --min-gap "$MIN_GAP_SECONDS" &>/dev/null || true
+fi
+
+exit 0

package/src/hooks/session-stop.sh

@@ -12,6 +12,32 @@ PAI_OS="pai"
 command -v "$PAI_OS" &>/dev/null || exit 0
 command -v sqlite3 &>/dev/null || exit 0
 
+# ---------------------------------------------------------------------------
+# Read the Claude session UUID from the hook payload
+# ---------------------------------------------------------------------------
+# Claude Code delivers the Stop event as JSON on stdin, carrying `session_id`.
+# That UUID is the only stable handle on this session: the steps below rename
+# (`session slug --apply`) and renumber (`session cleanup --execute`) the
+# session note, so anything derived from its filename has already changed by
+# the time the handover runs. Passing the UUID through is what lets the
+# handover recognise a checkpoint `pai pause` wrote minutes earlier instead of
+# mistaking it for a stale one and overwriting it.
+#
+# Read non-blocking: when no payload is piped in, carry on without it.
+
+CLAUDE_SESSION_UUID=""
+if [ ! -t 0 ]; then
+  HOOK_INPUT=$(timeout 2 cat 2>/dev/null || true)
+  if [ -n "$HOOK_INPUT" ]; then
+    if command -v jq &>/dev/null; then
+      CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | jq -r '.session_id // empty' 2>/dev/null || true)
+    else
+      CLAUDE_SESSION_UUID=$(printf '%s' "$HOOK_INPUT" | python3 -c \
+        "import sys,json; print(json.load(sys.stdin).get('session_id',''))" 2>/dev/null || true)
+    fi
+  fi
+fi
+
 REGISTRY_DB="$HOME/.pai/registry.db"
 [ -f "$REGISTRY_DB" ] || exit 0
 
@@ -88,7 +114,12 @@ fi
 # a handover section. If the command doesn't exist yet, fail gracefully.
 #
 
-"$PAI_OS" session handover "$PROJECT_SLUG" latest 2>/dev/null || true
+if [ -n "$CLAUDE_SESSION_UUID" ]; then
+  "$PAI_OS" session handover "$PROJECT_SLUG" latest \
+    --session-id "$CLAUDE_SESSION_UUID" 2>/dev/null || true
+else
+  "$PAI_OS" session handover "$PROJECT_SLUG" latest 2>/dev/null || true
+fi
 
 # Set tab color to completed state when session ends
 TAB_COLOR="${PAI_DIR:-$HOME/.claude}/tab-color-command.sh"