syntaur 0.6.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/claude-code/README.md

@@ -4,10 +4,10 @@ Syntaur plugin for Claude Code. Installed automatically during `syntaur setup`.
 
 ## What's included
 
-- **Skills:** grab-assignment, plan-assignment, complete-assignment, create-project, create-assignment, syntaur-protocol
+- **Skills:** grab-assignment, plan-assignment, complete-assignment, create-project, create-assignment, syntaur-protocol, save-session-summary
 - **Agents:** syntaur-protocol (background)
-- **Hooks:** write boundary enforcement (PreToolUse)
-- **Commands:** track-session
+- **Hooks:** write boundary enforcement (PreToolUse), session-start, session-end, **PreCompact** (prompts the agent to `/save-session-summary` before context is compacted)
+- **Commands:** track-session, save-session-summary
 - **References:** protocol docs
 
 ## Manual install

package/platforms/claude-code/agents/syntaur-expert.md

@@ -59,8 +59,11 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
           progress.md                # Agent-writable, append-only: timestamped progress log
           comments.md                # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md              # Agent-writable: working notes
-          handoff.md                 # Agent-writable: append-only handoff log
+          handoff.md                 # Agent-writable: append-only cross-ticket outbound at completion
           decision-record.md         # Agent-writable: append-only decision log
+          sessions/
+            <session-id>/
+              summary.md             # Agent-writable: per-session continuity (single doc, overwritten)
       resources/
         _index.md                    # Derived
         <resource-slug>.md           # Shared-writable
@@ -76,6 +79,7 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
       scratchpad.md
       handoff.md
       decision-record.md
+      sessions/<session-id>/summary.md  # Per-session continuity (same as project-nested)
 ```
 
 ---
@@ -90,8 +94,9 @@ Syntaur is a **markdown-based, filesystem-hosted protocol** that coordinates wor
 - `plan*.md` — versioned implementation plans (optional, one per `## Todos` entry: `plan.md`, `plan-v2.md`, ...)
 - `progress.md` — append-only timestamped progress log (newest first). Replaces the old `## Progress` body section.
 - `scratchpad.md` — unstructured working notes
-- `handoff.md` — append-only handoff log
+- `handoff.md` — append-only **assignment-level cross-ticket outbound** at completion (written by `complete-assignment`)
 - `decision-record.md` — append-only decision log
+- `sessions/<session-id>/summary.md` — **per-session continuity** for resume across sessions of the same agent on this assignment (written by `/save-session-summary`). Single document per session id, overwritten on each save. Distinct from `handoff.md`. Older summaries accumulate as immutable history; never delete.
 
 Only the assigned agent may write to its own assignment folder.
 
@@ -415,8 +420,11 @@ A: No. Single-writer guarantee — one agent per assignment folder. Use separate
 **Q: What if I need to ask the human a question?**
 A: Run `syntaur comment <slug> "question text" --type question`. It appends to `comments.md`, which replaces the old `## Questions & Answers` body section. The question rolls up into `_status.md`'s `openQuestions` counter and shows on the dashboard. Do NOT set status to `blocked` for questions — `blocked` is for runtime obstacles only.
 
-**Q: What goes in `progress.md` vs `handoff.md`?**
-A: `progress.md` is a continuous reverse-chron log of what you've done — append an entry per meaningful work unit. `handoff.md` is only written when you hand off work (to another agent or human), and summarizes the state at that transition.
+**Q: What goes in `progress.md` vs `handoff.md` vs `sessions/<sid>/summary.md`?**
+A: Three distinct artifacts.
+- `progress.md`: continuous reverse-chron log of what you've done — one entry per meaningful work unit, append-only.
+- `handoff.md`: **assignment-level cross-ticket outbound**, written at completion (via `complete-assignment`) for the next ticket / agent / human reviewer. Append-only.
+- `sessions/<session-id>/summary.md`: **session-scoped mid-assignment continuity**, written via `/save-session-summary` before compaction or session end so a future session of the same agent can resume cleanly. Single doc per session id, overwritten on save. The Claude Code `PreCompact` hook reminds you to invoke this; the SessionStart hook surfaces the latest one as `latestSessionSummaryPath` in `.syntaur/context.json`.
 
 **Q: How do I route work to another assignment without breaking the single-writer rule?**
 A: Run `syntaur request <target> "text"` — it appends a todo to the target's `## Todos` annotated `(from: <source>)`. This is a CLI-mediated exception to the single-writer rule.

package/platforms/claude-code/commands/save-session-summary/save-session-summary.md

@@ -0,0 +1,24 @@
+---
+name: save-session-summary
+description: Write a per-session continuity summary so a future session can resume this assignment cleanly
+arguments:
+  - name: args
+    description: "(none) — the skill reads .syntaur/context.json and the current session"
+    required: false
+---
+
+# /save-session-summary
+
+Thin wrapper that invokes the `save-session-summary` skill. The skill lives in `~/.claude/skills/save-session-summary/` (installed by `syntaur setup` / `syntaur install-plugin`) and contains the full protocol — writing `<assignmentDir>/sessions/<sessionId>/summary.md` without touching `handoff.md`.
+
+This is **mid-assignment session continuity**, not cross-ticket handoff:
+- Use `/save-session-summary` when you're about to compact, when you'll resume in a new session, or when the user asks to "save the session".
+- Use `/complete-assignment` (which writes `handoff.md`) when finishing the assignment for downstream review.
+
+## Instructions
+
+Invoke the `save-session-summary` skill via the Skill tool, passing the user's arguments. The skill handles everything else.
+
+Arguments: $ARGUMENTS
+
+If the skill is not installed, tell the user to run `syntaur install-plugin` (or `syntaur setup` if they haven't set up yet).

package/platforms/claude-code/hooks/hooks.json

@@ -12,6 +12,16 @@
         ]
       }
     ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Before compaction, if there is an active Syntaur assignment (check `.syntaur/context.json` for `assignmentDir` and `sessionId`), invoke `/save-session-summary` to write `<assignmentDir>/sessions/<sessionId>/summary.md` so a future session can resume cleanly. Skip silently if no active Syntaur context. Do NOT write to `handoff.md` — that is reserved for cross-ticket handoff at completion."
+          }
+        ]
+      }
+    ],
     "SessionStart": [
       {
         "hooks": [

package/platforms/claude-code/hooks/session-start.sh

@@ -36,11 +36,36 @@ CONTEXT_FILE="$CWD/.syntaur/context.json"
 # Always replace both sessionId and transcriptPath together. If the incoming
 # transcript_path is empty, explicitly null the stored transcriptPath so a new
 # session never inherits a stale transcript path from the prior session.
+#
+# Also resolve the latest session-summary path (mid-assignment continuity) so
+# the resuming agent's first protocol-read can pick it up. Selection rule:
+# the summary.md with the most recent file mtime under
+# <assignmentDir>/sessions/*/summary.md. Null if none exists.
+ASSIGNMENT_DIR_RAW=$(jq -r '.assignmentDir // empty' "$CONTEXT_FILE" 2>/dev/null)
+ASSIGNMENT_DIR="${ASSIGNMENT_DIR_RAW/#\~/$HOME}"
+
+LATEST_SUMMARY=""
+if [ -n "$ASSIGNMENT_DIR" ] && [ -d "$ASSIGNMENT_DIR/sessions" ]; then
+  # Prefer GNU-style stat formatting if available (Linux); fall back to BSD
+  # (macOS). Resolve newest-by-mtime portably.
+  while IFS= read -r -d '' f; do
+    if M=$(stat -f '%m' "$f" 2>/dev/null) || M=$(stat -c '%Y' "$f" 2>/dev/null); then
+      printf '%s\t%s\n' "$M" "$f"
+    fi
+  done < <(find "$ASSIGNMENT_DIR/sessions" -mindepth 2 -maxdepth 2 -type f -name 'summary.md' -print0 2>/dev/null) \
+    | sort -rn -k1,1 \
+    | head -1 \
+    | cut -f2- > "${CONTEXT_FILE}.summary.tmp.$$" 2>/dev/null
+  LATEST_SUMMARY=$(cat "${CONTEXT_FILE}.summary.tmp.$$" 2>/dev/null || true)
+  rm -f "${CONTEXT_FILE}.summary.tmp.$$"
+fi
+
 TMP="${CONTEXT_FILE}.tmp.$$"
 jq \
   --arg sid "$SESSION_ID" \
   --arg tp "$TRANSCRIPT_PATH" \
-  '. + {sessionId: $sid, transcriptPath: (if ($tp | length) > 0 then $tp else null end)}' \
+  --arg lsp "$LATEST_SUMMARY" \
+  '. + {sessionId: $sid, transcriptPath: (if ($tp | length) > 0 then $tp else null end), latestSessionSummaryPath: (if ($lsp | length) > 0 then $lsp else null end)}' \
   "$CONTEXT_FILE" > "$TMP" 2>/dev/null \
   && mv "$TMP" "$CONTEXT_FILE" 2>/dev/null \
   || rm -f "$TMP"

package/platforms/claude-code/references/file-ownership.md

@@ -18,8 +18,9 @@ You may ONLY write to files inside your assigned assignment folder:
 | `plan*.md` | Versioned implementation plans (optional, 0 or more: `plan.md`, `plan-v2.md`, ...) — each linked from a todo in `assignment.md` |
 | `progress.md` | Append-only timestamped progress log (newest first). Replaces the old `## Progress` body section. |
 | `scratchpad.md` | Working notes |
-| `handoff.md` | Append-only handoff log |
+| `handoff.md` | Append-only **assignment-level cross-ticket outbound** at completion (written by `complete-assignment`) |
 | `decision-record.md` | Append-only decision log |
+| `sessions/<session-id>/summary.md` | **Per-session continuity** for resume across sessions of the same agent on this assignment. Single document per session id, overwritten on every save (written by `/save-session-summary`). Not the same as `handoff.md`. |
 
 Path pattern (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
 Path pattern (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/`

package/platforms/claude-code/references/protocol-summary.md

@@ -22,8 +22,11 @@ Protocol version: **2.0**
           progress.md        # Agent-writable, append-only: timestamped progress log
           comments.md        # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md      # Agent-writable: working notes
-          handoff.md         # Agent-writable: append-only handoff log
+          handoff.md         # Agent-writable: append-only cross-ticket outbound at completion
           decision-record.md # Agent-writable: append-only decision log
+          sessions/
+            <session-id>/
+              summary.md     # Agent-writable: per-session continuity (single doc, overwritten)
       resources/
         _index.md            # Derived (read-only)
         <resource-slug>.md   # Shared-writable
@@ -39,6 +42,7 @@ Protocol version: **2.0**
       scratchpad.md
       handoff.md
       decision-record.md
+      sessions/<session-id>/summary.md  # Per-session continuity, same as project-nested
   playbooks/
     manifest.md              # Derived: playbook listing (read-only)
     <slug>.md                # User-authored: behavioral rules for agents
@@ -83,3 +87,4 @@ Protocol version: **2.0**
 9. **Progress** is appended to `progress.md` as timestamped entries (newest first). Do not add a `## Progress` section to `assignment.md`.
 10. **Comments** are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly. Questions carry a `resolved` flag.
 11. **Cross-assignment work** is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
+12. **Session continuity** (mid-assignment) lives at `sessions/<session-id>/summary.md` inside the assignment dir — one document per session id, overwritten on every save (via `/save-session-summary`). On resume, pick the latest by `summary.md` file mtime; the Claude Code SessionStart hook also stashes the absolute path in `.syntaur/context.json` as `latestSessionSummaryPath`. Older summaries accumulate as immutable history; never delete them. Distinct from `handoff.md`, which is the assignment-level cross-ticket outbound at completion. `syntaur doctor` intentionally ignores `sessions/`. The Claude Code `PreCompact` hook reminds the agent to invoke `/save-session-summary` before context is compacted.

package/platforms/claude-code/skills/track-session/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: track-session
+description: Use when the user asks to track, register, or log this Claude Code session in the Syntaur dashboard — standalone or linked to a project/assignment. Triggers on "/track-session", "track this session", "register this session in syntaur", or similar.
+---
+
+# Track Session
+
+Register the current Claude Code session as an agent session in the Syntaur dashboard. Works standalone or linked to a project/assignment.
+
+Only real Claude Code session IDs are accepted — no synthesis. The real id is written to `.syntaur/context.json` by the SessionStart hook, with `~/.claude/sessions/<pid>.json` as the fallback source.
+
+## Usage
+
+User arguments: `$ARGUMENTS`
+
+- (no args) — register a standalone session
+- `--description "<text>"` — with a description
+- `--project <slug> --assignment <slug>` — linked to a project
+- `--description "<text>" --project <slug> --assignment <slug>` — both
+
+## Workflow
+
+### Step 1: Parse arguments
+
+Extract optional flags from the argument string:
+- `--description "<text>"` or `--description <text>` — session description
+- `--project <slug>` — project to link to
+- `--assignment <slug>` — assignment to link to
+
+### Step 2: Source the real session id + transcript path
+
+In priority order:
+
+1. Read `.syntaur/context.json` if present. If it contains `sessionId`, use it. Also pick up `transcriptPath` if present.
+2. Otherwise, read the most-recently-modified file under `~/.claude/sessions/*.json` whose `cwd` matches `$(pwd)` and use its `sessionId` field. The transcript path is conventionally `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; include it if the file exists, otherwise omit.
+3. If neither source yields an id, abort with: "Could not resolve a real Claude Code session id. Restart the Claude session so the SessionStart hook can populate `.syntaur/context.json`, or run `/rename <slug>` then try again."
+
+DO NOT generate a UUID. `syntaur track-session` rejects missing session IDs.
+
+### Step 3: Run the CLI command
+
+Run the track-session CLI via Bash (use `dangerouslyDisableSandbox: true` since it writes to `~/.syntaur/`):
+
+```bash
+syntaur track-session \
+  --agent claude \
+  --session-id "$SESSION_ID" \
+  --transcript-path "$TRANSCRIPT_PATH" \
+  --path "$(pwd)" \
+  [--description "<text>"] \
+  [--project <slug>] \
+  [--assignment <slug>]
+```
+
+Omit `--transcript-path` entirely (don't pass an empty string) if no transcript path could be resolved.
+
+The CLI prints one of:
+- `Registered standalone agent session <sessionId>.`
+- `Registered agent session <sessionId> for <assignment> in <project>.`
+
+Registration is idempotent — re-running the command with the same session id safely upserts project/assignment/description onto the existing row.
+
+### Step 4: Merge context.json
+
+Ensure `.syntaur/context.json` has the session fields (so SessionEnd and future `track-session` runs find them). Merge, don't overwrite:
+
+```bash
+mkdir -p .syntaur
+if [ -f .syntaur/context.json ]; then
+  jq --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '. + {sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    .syntaur/context.json > .syntaur/context.json.tmp \
+    && mv .syntaur/context.json.tmp .syntaur/context.json
+else
+  jq -n --arg sid "$SESSION_ID" --arg tp "$TRANSCRIPT_PATH" \
+    '{sessionId: $sid} + (if ($tp | length) > 0 then {transcriptPath: $tp} else {} end)' \
+    > .syntaur/context.json
+fi
+```
+
+### Step 5: Confirm
+
+Tell the user:
+- The session was registered (include the short session id).
+- It will be auto-stopped when this conversation ends via the SessionEnd hook.
+- If linked to a project, mention which project/assignment.

package/platforms/codex/README.md

@@ -4,9 +4,9 @@ Syntaur plugin for OpenAI Codex. Installed automatically during `syntaur setup`.
 
 ## What's included
 
-- **Skills:** syntaur-protocol, create-project, create-assignment, grab-assignment, plan-assignment, complete-assignment, track-session
+- **Skills:** syntaur-protocol, create-project, create-assignment, grab-assignment, plan-assignment, complete-assignment, track-session, save-session-summary
 - **Hooks:** write boundary enforcement, session cleanup
-- **Commands:** track-session
+- **Commands:** track-session, save-session-summary (Codex has no `PreCompact` event — invoke manually before compaction or session end)
 - **Agents:** syntaur-protocol (background)
 - **References:** protocol docs
 

package/platforms/codex/agents/syntaur-operator.md

@@ -11,7 +11,7 @@ Your job is to work fluently within the Syntaur protocol without breaking owners
 
 - Create projects and assignments (project-nested or standalone) with the `syntaur` CLI
 - Claim assignments and establish local assignment context
-- Keep `assignment.md`, active plan files (`plan.md`, `plan-v2.md`, ...), `progress.md`, and `handoff.md` accurate during execution
+- Keep `assignment.md`, active plan files (`plan.md`, `plan-v2.md`, ...), `progress.md`, `handoff.md` (cross-ticket outbound), and any active `sessions/<sid>/summary.md` (mid-assignment continuity) accurate during execution
 - Record questions/notes/feedback via `syntaur comment` and route cross-assignment work via `syntaur request`
 - Track Codex sessions for the Syntaur dashboard
 - Set up Codex adapter instructions in the active workspace
@@ -30,7 +30,8 @@ When a task involves Syntaur:
    - any `<assignmentDir>/plan*.md` files linked from active todos in the `## Todos` section
    - `<assignmentDir>/progress.md` (if present) — reverse-chron progress log
    - `<assignmentDir>/comments.md` (if present) — threaded questions/notes/feedback
-   - `<assignmentDir>/handoff.md`
+   - `<assignmentDir>/handoff.md` — cross-ticket outbound history
+   - the latest `<assignmentDir>/sessions/<sid>/summary.md` (selected by file mtime) if present — mid-assignment continuity from a prior session
 4. Resolve the workspace boundary from `.syntaur/context.json` or `assignment.md` frontmatter before editing code.
 
 Project-nested assignments live at `~/.syntaur/projects/<slug>/assignments/<aslug>/`. Standalone assignments live at `~/.syntaur/assignments/<uuid>/` — folder named by UUID, `project: null`, `slug` display-only.
@@ -51,8 +52,9 @@ Project-nested assignments live at `~/.syntaur/projects/<slug>/assignments/<aslu
   - `plan*.md` (0 or more versioned plan files, e.g., `plan.md`, `plan-v2.md`)
   - `progress.md` (append timestamped entries, newest first — replaces the old `## Progress` section)
   - `scratchpad.md`
-  - `handoff.md`
+  - `handoff.md` (append-only; **assignment-level cross-ticket outbound** at completion)
   - `decision-record.md`
+  - `sessions/<session-id>/summary.md` (**per-session continuity**; single doc per session id, overwritten on save by `/save-session-summary`. Codex has no `PreCompact` hook — invoke manually before compaction or session end.)
 - project `resources/*.md`
 - project `memories/*.md`
 - `.syntaur/context.json` in the current working directory
@@ -72,7 +74,7 @@ Project-nested assignments live at `~/.syntaur/projects/<slug>/assignments/<aslu
 - Update acceptance criteria and `## Todos` checkboxes as work lands.
 - Append timestamped entries to `progress.md` (not to `assignment.md`) after meaningful milestones.
 - When requirements shift, supersede the prior plan todo instead of rewriting the old plan file.
-- Append handoffs instead of replacing previous handoff entries.
+- Append handoff.md entries (cross-ticket outbound) instead of replacing previous handoff entries. Mid-assignment session continuity is a separate file: `sessions/<sid>/summary.md`, single document per session id, overwritten on each save. Do not delete older `sessions/*/summary.md` files at completion — they remain as immutable history.
 - Record questions via `syntaur comment ... --type question` — they roll up into `_status.md`'s `openQuestions` counter.
 
 ## CLI Reference

package/platforms/codex/commands/save-session-summary.md

@@ -0,0 +1,23 @@
+---
+description: Write a per-session continuity summary so a future Codex session can resume this assignment cleanly
+---
+
+# /save-session-summary
+
+Write a per-session continuity summary at `<assignmentDir>/sessions/<sessionId>/summary.md` so a future session can resume this assignment without re-reading the full transcript.
+
+This is **mid-assignment session continuity**, not cross-ticket handoff:
+- Use `/save-session-summary` when about to compact, before ending a session, or when the user asks to "save the session".
+- Use the `complete-assignment` skill (which writes `handoff.md`) when finishing the assignment for downstream review.
+
+Codex has no `PreCompact` hook event — invoke this command manually.
+
+## Workflow
+
+Follow the `save-session-summary` skill in full. Summary:
+
+1. Read `.syntaur/context.json`. Required: `assignmentDir`, `sessionId`. If `sessionId` is missing, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not synthesize a session id.
+2. Create `<assignmentDir>/sessions/<sessionId>/` only at write time (avoid empty dirs).
+3. Write or overwrite `<assignmentDir>/sessions/<sessionId>/summary.md` with frontmatter (`assignment`, `sessionId`, `created`, `updated`) and body sections: `## Snapshot`, `## What Was Done`, `## What's Next`, `## Open Questions`, `## Load-Bearing Context`. Single document per session id — directory partitions by session.
+4. Do NOT modify `handoff.md`.
+5. Optionally append a brief progress entry noting the save.

package/platforms/codex/references/file-ownership.md

@@ -18,8 +18,9 @@ You may only write to files inside your assigned assignment folder:
 | `plan*.md` | Versioned implementation plans (optional, 0 or more: `plan.md`, `plan-v2.md`, ...) — each linked from a todo in `assignment.md` |
 | `progress.md` | Append-only timestamped progress log (newest first). Replaces the old `## Progress` body section. |
 | `scratchpad.md` | Working notes |
-| `handoff.md` | Append-only handoff log |
+| `handoff.md` | Append-only **assignment-level cross-ticket outbound** at completion (written by `complete-assignment`) |
 | `decision-record.md` | Append-only decision log |
+| `sessions/<session-id>/summary.md` | **Per-session continuity** for resume across sessions of the same agent on this assignment. Single document per session id, overwritten on every save (written by `/save-session-summary`). Codex has no `PreCompact` hook — invoke manually. |
 
 Path pattern (project-nested): `~/.syntaur/projects/<project>/assignments/<your-assignment>/`
 Path pattern (standalone): `~/.syntaur/assignments/<your-assignment-uuid>/`

package/platforms/codex/references/protocol-summary.md

@@ -22,8 +22,11 @@ Protocol version: **2.0**
           progress.md        # Agent-writable, append-only: timestamped progress log
           comments.md        # CLI-mediated: threaded questions/notes/feedback (via `syntaur comment`)
           scratchpad.md      # Agent-writable: working notes
-          handoff.md         # Agent-writable: append-only handoff log
+          handoff.md         # Agent-writable: append-only cross-ticket outbound at completion
           decision-record.md # Agent-writable: append-only decision log
+          sessions/
+            <session-id>/
+              summary.md     # Agent-writable: per-session continuity (single doc, overwritten)
       resources/
         _index.md            # Derived (read-only)
         <resource-slug>.md   # Shared-writable
@@ -39,6 +42,7 @@ Protocol version: **2.0**
       scratchpad.md
       handoff.md
       decision-record.md
+      sessions/<session-id>/summary.md  # Per-session continuity, same as project-nested
   playbooks/
     manifest.md              # Derived: playbook listing (read-only)
     <slug>.md                # User-authored: behavioral rules for agents
@@ -83,3 +87,4 @@ Protocol version: **2.0**
 9. Progress is appended to `progress.md` as timestamped entries (newest first). Do not add a `## Progress` section to `assignment.md`.
 10. Comments are appended to `comments.md` via `syntaur comment <slug> "body" [--type question|note|feedback] [--reply-to <id>]`. Never edit `comments.md` directly.
 11. Cross-assignment work is requested via `syntaur request <source> <target> "text"` — appends to the target's `## Todos` annotated `(from: <source>)`.
+12. Session continuity (mid-assignment) lives at `sessions/<session-id>/summary.md` inside the assignment dir — one document per session id, overwritten on every save (via `/save-session-summary`). On resume, pick the latest by `summary.md` file mtime. Older summaries accumulate as immutable history; never delete them. Distinct from `handoff.md`, which is the assignment-level cross-ticket outbound at completion. `syntaur doctor` intentionally ignores `sessions/`. **Codex has no `PreCompact` hook event** — invoke `/save-session-summary` manually before compaction or session end.

package/vendor/syntaur-skills/skills/complete-assignment/SKILL.md

@@ -63,6 +63,8 @@ Do NOT add a `## Progress` section to `assignment.md` — progress entries live
 
 ## Step 4: Write Handoff Entry
 
+`handoff.md` is the **assignment-level cross-ticket outbound** doc — written here, at completion, for the next ticket / agent / human reviewer. It is NOT the mid-assignment session continuity artifact; that lives at `<assignmentDir>/sessions/<sid>/summary.md` and is written by `/save-session-summary`. Any `sessions/*/summary.md` files are reference-only at completion time and MUST NOT be deleted — they remain as immutable historical context.
+
 Read `<assignmentDir>/handoff.md` to see its current content and frontmatter.
 
 Append a new handoff entry to the markdown body. Read the current `handoffCount` from the frontmatter and use `handoffCount + 1` as the entry number. The entry must follow this format:

package/vendor/syntaur-skills/skills/grab-assignment/SKILL.md

@@ -69,7 +69,11 @@ If either command fails, report the error and stop.
 
 ## Step 4: Read Assignment Context and Backfill Workspace
 
-Read the full assignment file. Also read `comments.md` if present (inherited questions / notes). For each `dependsOn` entry, read the dependency's `handoff.md` AND `decision-record.md` so upstream decisions carry forward.
+Read the full assignment file. Also read `comments.md` if present (inherited questions / notes).
+
+For each `dependsOn` entry, read the dependency's `handoff.md` AND `decision-record.md` so upstream decisions carry forward. (`handoff.md` is the **cross-ticket outbound** doc — distinct from session continuity.)
+
+If `<assignmentDir>/sessions/` exists, also read the most recent `<assignmentDir>/sessions/<sid>/summary.md` (selected by `summary.md` file mtime). This is the **mid-assignment session continuity** artifact written by `/save-session-summary` at the end of a prior session of the same assignment. Treat its `What's Next` and `Load-Bearing Context` sections as resume context. (Note: in Claude Code, the SessionStart hook also stashes this path into context.json as `latestSessionSummaryPath` — same semantics; either source is fine.)
 
 From the assignment frontmatter extract: `title`, `workspace.repository`, `workspace.worktreePath`, `workspace.branch`, `dependsOn`, `priority`.
 
@@ -155,4 +159,5 @@ Summarize:
 - Active todos from `## Todos`, including any linked plan files.
 - The workspace path.
 - Any inherited comments/questions from `comments.md`.
-- Suggested next step: `plan-assignment` to create an implementation plan.
+- **Resume context** (if Step 4 found a `sessions/<sid>/summary.md`): a short block citing the session id and the timestamp of that summary's `updated` frontmatter, followed by its `What's Next` bullets. This is mid-assignment continuity — distinct from any cross-ticket handoff.
+- Suggested next step: `plan-assignment` to create an implementation plan, or — if a session summary's `What's Next` is concrete — proceed directly with the next step it names.

package/vendor/syntaur-skills/skills/plan-assignment/SKILL.md

@@ -50,7 +50,9 @@ Read these files to understand the assignment:
 
 Per-project `agent.md` / `claude.md` were removed in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/` (already loaded in Step 2).
 
-If the assignment has dependencies (`dependsOn` in frontmatter), read each dependency's `handoff.md` AND `decision-record.md` for integration context and upstream decisions.
+If the assignment has dependencies (`dependsOn` in frontmatter), read each dependency's `handoff.md` AND `decision-record.md` for integration context and upstream decisions. (`handoff.md` is cross-ticket outbound — distinct from session continuity.)
+
+If `<assignmentDir>/sessions/` exists, also read the most recent `sessions/<sid>/summary.md` (selected by `summary.md` file mtime). This is mid-assignment continuity from a prior session of the same assignment — its `What's Next`, `Open Questions`, and `Load-Bearing Context` sections are direct planning inputs when resuming work that was already in flight.
 
 ## Step 4: Explore Workspace (if set)
 

package/vendor/syntaur-skills/skills/save-session-summary/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: save-session-summary
+description: >-
+  Write a per-session continuity summary so a future session can resume cleanly
+  without re-reading the full transcript. Use when the user asks to save session
+  state, prepare to compact, or hand off mid-assignment to a new session of the
+  same agent. Triggered by `/save-session-summary`, by Claude Code's PreCompact
+  hook, or when the user says "save the session" / "before we compact" / similar.
+license: MIT
+metadata:
+  author: prong-horn
+  version: "1.0.0"
+---
+
+# Save Session Summary
+
+Write or overwrite the current session's continuity summary at
+`<assignmentDir>/sessions/<sessionId>/summary.md`. This is **session-scoped
+mid-assignment continuity** — distinct from `handoff.md`, which is the
+**assignment-level cross-ticket outbound** doc written by `complete-assignment`.
+
+## When NOT to use this skill
+
+- Use `complete-assignment` instead when finishing the assignment for a downstream ticket / human reviewer — that writes `handoff.md`.
+- Do not write to `handoff.md` here. The two artifacts are separate.
+
+## Step 1: Load Context
+
+Read `.syntaur/context.json` from the current working directory.
+
+If the file does not exist, tell the user: "No active assignment found. Run `grab-assignment` first." and stop.
+
+Extract:
+- `assignmentDir` (absolute path) — required.
+- `sessionId` — required, must be the real agent runtime session id.
+
+If `sessionId` is missing, empty, or `null`, abort with: "Session not tracked. Run `syntaur track-session ...` first." Do not invent or generate a session id.
+
+## Step 2: Ensure Session Directory
+
+Create `<assignmentDir>/sessions/<sessionId>/` only at this step (not earlier — empty session dirs are noise). Use `mkdir -p` semantics so re-saves are idempotent.
+
+## Step 3: Read Existing Summary (if any)
+
+If `<assignmentDir>/sessions/<sessionId>/summary.md` already exists, read it and preserve its `created` frontmatter timestamp. Otherwise, the new file's `created` is now.
+
+This is a **single document per session id** — every save in the same session overwrites in place. The directory partitions by session id, so older sessions remain on disk as immutable history.
+
+## Step 4: Write the Summary
+
+Write `<assignmentDir>/sessions/<sessionId>/summary.md` with this structure (overwrite if it exists). Fill the section bodies with content derived from this session's actual work — be specific and concrete, this is what a future session will load to resume.
+
+```markdown
+---
+assignment: <assignment-slug>
+sessionId: <session-id>
+created: "<original created timestamp, or now if new>"
+updated: "<now, ISO 8601>"
+---
+
+# Session Summary
+
+## Snapshot
+
+<One paragraph: what the assignment is, where work currently stands, what is load-bearing for a future session to know immediately on resume.>
+
+## What Was Done
+
+- <Concrete action 1>
+- <Concrete action 2>
+- ...
+
+## What's Next
+
+- <Most important next step>
+- <Subsequent steps in order>
+- ...
+
+## Open Questions
+
+- <Unresolved question or decision>
+- <Ambiguity to resolve>
+- ...
+(or "None." if no open items)
+
+## Load-Bearing Context
+
+- File paths + line numbers that matter for resume
+- Command outputs the next session will need
+- Decisions made this session that aren't captured in `decision-record.md`
+- External references (PRs, issues, docs) that scope the next steps
+```
+
+## Step 5: Confirm — Do NOT Touch handoff.md
+
+Verify your write did not modify `<assignmentDir>/handoff.md`. The two artifacts are deliberately separate:
+
+| File | Scope | When written | Audience |
+|------|-------|--------------|----------|
+| `handoff.md` | Assignment-level | At completion (via `complete-assignment`) | Next ticket / agent / human reviewer |
+| `sessions/<sid>/summary.md` | Session-scoped | Mid-assignment, on demand or pre-compact | Future session of the same agent on the same assignment |
+
+## Step 6: Append a Progress Entry (optional but recommended)
+
+If progress hasn't already been logged in this turn, append a brief entry to `<assignmentDir>/progress.md` noting that a session summary was saved and the next-step pointer.
+
+## Step 7: Report to User
+
+Summarize:
+- Path of the written summary
+- Session id
+- Number of items in "What's Next" (so the user knows resume scope)
+- Reminder: this is mid-assignment continuity, not cross-ticket handoff

package/vendor/syntaur-skills/skills/syntaur-protocol/SKILL.md

@@ -26,8 +26,9 @@ Respect file ownership boundaries. The Claude Code and Codex plugins enforce the
    - `plan*.md` (versioned — `plan.md`, `plan-v2.md`, etc.)
    - `progress.md` (append-only, timestamped)
    - `scratchpad.md`
-   - `handoff.md` (append-only)
+   - `handoff.md` (append-only — **assignment-level cross-ticket outbound**)
    - `decision-record.md` (append-only)
+   - `sessions/<sessionId>/summary.md` (**session-scoped mid-assignment continuity** — single document per session id, overwritten on save)
 2. **Project-level shared files:**
    - `~/.syntaur/projects/<project>/resources/<slug>.md`
    - `~/.syntaur/projects/<project>/memories/<slug>.md`
@@ -49,6 +50,22 @@ Respect file ownership boundaries. The Claude Code and Codex plugins enforce the
 
 Per-project `agent.md` / `claude.md` do NOT exist in protocol v2.0. Agent-level conventions now live at the repo root (`CLAUDE.md` / `AGENTS.md`) and in `~/.syntaur/playbooks/`.
 
+## Session Continuity vs Cross-Ticket Handoff
+
+Two related but distinct artifacts. Conflating them is a recurring mistake.
+
+| Artifact | Scope | When written | Audience | Written by |
+|---|---|---|---|---|
+| `handoff.md` | Assignment-level | At completion | The next ticket / agent / human reviewer | `complete-assignment` skill |
+| `sessions/<sessionId>/summary.md` | Session-scoped | Mid-assignment, before compaction or at session end | A future session of the same agent on the same assignment | `save-session-summary` skill |
+
+Rules:
+- One `summary.md` per session id directory; overwrite on every save.
+- Older `sessions/<sid>/summary.md` files accumulate as immutable history — never delete them, even at completion.
+- Resume picks the latest by `summary.md` file mtime. The Claude Code SessionStart hook also stashes that absolute path into `.syntaur/context.json` as `latestSessionSummaryPath` for convenience; either source is fine.
+- Codex has no `PreCompact` hook — Codex agents invoke `/save-session-summary` manually before compaction or session end.
+- `syntaur doctor` intentionally does NOT validate `sessions/` — sessions are optional and absence is not anomalous.
+
 ## Current Assignment Context
 
 If `.syntaur/context.json` exists in the current working directory, read it before making changes. Fields you will see:
@@ -60,6 +77,7 @@ If `.syntaur/context.json` exists in the current working directory, read it befo
 - `workspaceRoot` — absolute path to the code workspace
 - `sessionId` — real agent-runtime session id (never a synthesized UUID)
 - `transcriptPath` — absolute path to the agent's rollout/transcript file, if known
+- `latestSessionSummaryPath` — absolute path to the most recent `sessions/<sid>/summary.md` (Claude Code SessionStart hook resolves this; `null` if none)
 
 ## Required Reading Order
 
@@ -71,8 +89,9 @@ When starting work on an existing assignment, read these in order:
 4. `<assignmentDir>/assignment.md`
 5. `<assignmentDir>/comments.md` if present — inherited questions / notes
 6. Latest `<assignmentDir>/plan*.md` (pick the newest)
-7. `<assignmentDir>/handoff.md` — history
-8. For each `dependsOn` entry: the dependency's `handoff.md` AND `decision-record.md` — upstream integration context and accepted decisions carry forward
+7. `<assignmentDir>/handoff.md` — cross-ticket outbound history (entries from prior agents/humans handing this assignment off)
+8. The latest `<assignmentDir>/sessions/<sid>/summary.md` if present (mid-assignment resume context from a prior session of this assignment) — selected by `summary.md` file mtime, or via `latestSessionSummaryPath` in context.json on Claude Code
+9. For each `dependsOn` entry: the dependency's `handoff.md` AND `decision-record.md` — upstream integration context and accepted decisions carry forward
 
 ## Lifecycle Commands
 
@@ -108,7 +127,7 @@ ls ~/.syntaur/playbooks/*.md 2>/dev/null
 - Append milestones to `progress.md` — do NOT add a `## Progress` section to `assignment.md` (v2.0 moved progress to its own file).
 - `## Todos` in `assignment.md` is an informal markdown checklist. Items may be simple tasks or markdown links to plan files. When a plan is superseded, mark the old todo as `- [x] ~~Execute [plan](./plan.md)~~ (superseded by plan-v2)` — never delete. `## Todos` is also the landing spot for cross-assignment `syntaur request` entries.
 - Record questions / notes / feedback via `syntaur comment` — never edit `comments.md` directly. Do NOT set status to `blocked` just because there is an open question; block only for a real external dependency with a `--reason`.
-- Write handoffs with enough context for another agent or human to continue cleanly. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
+- Write `handoff.md` entries (via `complete-assignment`) with enough context for another agent or human to continue cleanly **across tickets**. Write `sessions/<sid>/summary.md` (via `/save-session-summary`) for mid-assignment continuity within the same assignment across sessions of the same agent. Do not mix the two. Record decisions in `decision-record.md` with Status / Context / Decision / Consequences — downstream dependents auto-load these during grab.
 - Commit frequently with messages referencing the assignment slug.
 
 ## References

package/vendor/syntaur-skills/skills/syntaur-protocol/references/file-ownership.md

@@ -22,8 +22,9 @@ You may only write to files inside your currently-claimed assignment folder:
 | `plan*.md` | Versioned implementation plans (`plan.md`, `plan-v2.md`, ...). When superseded, the old plan's todo is marked superseded but the file itself is never deleted. |
 | `progress.md` | Append-only, timestamped progress log (newest first). |
 | `scratchpad.md` | Working notes. |
-| `handoff.md` | Append-only handoff log. |
+| `handoff.md` | Append-only **assignment-level cross-ticket outbound** at completion (written by `complete-assignment`). |
 | `decision-record.md` | Append-only decision log (Status / Context / Decision / Consequences). |
+| `sessions/<session-id>/summary.md` | **Per-session continuity** for resume across sessions of the same agent on this assignment. Single document per session id, overwritten on every save (written by `/save-session-summary`). Not the same as `handoff.md`. |
 
 Path patterns:
 - Project-nested: `~/.syntaur/projects/<project>/assignments/<your-assignment-slug>/`