cristoslc Session Teardown
Single entry point for ending a session. Runs the full shutdown sequence: digest, retro, merge, cleanup, close, commit. Replaces the former swain-session close handler (ADR-023).
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null
If session-chain is NOT passed and the JSON output has "status" other than "active", inform the operator: "No active session to tear down." Exit cleanly with code 0.
What this skill does
Session teardown runs a sequence of hygiene checks before a session closes:
- Orphan worktree detection — finds worktrees with no corresponding session bookmark (SPEC-233: actionable with safety checks)
- Git dirty-state check — surfaces uncommitted changes before the operator leaves
- Completion pipeline check — verifies BDD, smoke, and retro ran; invokes missing steps (SPEC-258)
- Ticket sync prompt — prompts the operator to verify tickets match what was done (SPEC-234: notes degraded state if no session)
- Handoff summary — appends a session summary to SESSION-ROADMAP.md
Note on retro: The SPEC-level retro now runs as part of the completion pipeline (Step 3 / swain-do Step 2d). The EPIC-level retro is invoked by swain-session's close handler. Teardown invokes retro only as a catch-up if the pipeline's retro step was missed.
Step 0 — Release current lockfile claim (SPEC-247)
If the current session is running in a worktree with an active lockfile, release the claim. This runs first so that subsequent orphan detection does not flag the current worktree as active.
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
LOCKFILE_SCRIPT="$REPO_ROOT/.agents/bin/swain-lockfile.sh"
GIT_COMMON=$(git rev-parse --git-common-dir 2>/dev/null)
GIT_DIR=$(git rev-parse --git-dir 2>/dev/null)
if [ "$GIT_COMMON" != "$GIT_DIR" ] && [ -f "$LOCKFILE_SCRIPT" ]; then
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
bash "$LOCKFILE_SCRIPT" release "$BRANCH" 2>/dev/null || true
fi
Step 1 — Orphan worktree check (SPEC-233, SPEC-247)
This step reads worktree bookmarks from the worktrees array in session.json and cross-references lockfile state (SPEC-247). Orphan worktrees are offered for operator-confirmed removal with safety checks. This step always runs regardless of --session-chain.
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SESSION_FILE="$REPO_ROOT/.agents/session.json"
LOCKFILE_SCRIPT="$REPO_ROOT/.agents/bin/swain-lockfile.sh"
# Build a list of bookmarked worktree paths from session.json
bookmarked_wts=$(jq -r '(.worktrees // [])[] | .path' "$SESSION_FILE" 2>/dev/null)
orphan_candidates=()
orphan_results=()
ready_candidates=()
# Get all physical worktrees
git worktree list --porcelain 2>/dev/null | grep "^worktree " | while read -r line; do
wt_path="${line#worktree }"
wt_branch="$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null)"
# Skip trunk (protected)
if [ "$wt_path" = "$REPO_ROOT" ]; then
echo "protected: $wt_path (trunk)"
continue
fi
# Check lockfile state (SPEC-247)
if [ -f "$LOCKFILE_SCRIPT" ]; then
lock_branch="${wt_branch##*/}" # strip refs/heads/ prefix
lockfile="$REPO_ROOT/.agents/worktrees/${lock_branch}.lock"
if [ -f "$lockfile" ]; then
# Check if ready_for_cleanup — safe to remove without confirmation
if grep -q 'ready_for_cleanup=true' "$lockfile" 2>/dev/null; then
echo "ready: $wt_path ($wt_branch) — marked ready_for_cleanup"
ready_candidates+=("$wt_path|$wt_branch|$lockfile")
continue
fi
# Check if actively claimed by another session
if ! bash "$LOCKFILE_SCRIPT" is-stale "$lock_branch" >/dev/null 2>&1; then
echo "claimed: $wt_path ($wt_branch) — active lockfile, skip"
continue
fi
fi
fi
# Check if bookmarked in session.json
is_orphan=true
reason=""
if echo "$bookmarked_wts" | grep -qF "$wt_path"; then
is_orphan=false
echo "linked: $wt_path ($wt_branch)"
fi
if [ "$is_orphan" = true ]; then
# Safety checks per SPEC-233 AC1-AC3
if [ "$wt_path" = "$(pwd)" ]; then
reason="current directory"
elif [ -n "$(git -C "$wt_path" status --porcelain 2>/dev/null)" ]; then
reason="uncommitted changes"
elif ! git merge-base --is-ancestor "$wt_branch" trunk 2>/dev/null; then
reason="branch not fully merged"
else
reason="safe to remove"
orphan_candidates+=("$wt_path|$wt_branch")
fi
echo "orphan: $wt_path ($wt_branch) — $reason"
orphan_results+=("$wt_path|$wt_branch|$reason")
fi
done
If orphan worktrees are found, display the message: "The following worktrees have no active session bookmark — consider removing them."
Auto-remove ready_for_cleanup worktrees (SPEC-247)
Worktrees marked ready_for_cleanup have been merged and pushed — safe to remove without operator confirmation. Archive session.json first (SPEC-248):
ARCHIVE_SCRIPT="$REPO_ROOT/.agents/bin/swain-session-archive.sh"
for candidate in "${ready_candidates[@]}"; do
IFS='|' read -r wt_path wt_branch lockfile <<< "$candidate"
# Archive session.json before deletion
if [ -f "$ARCHIVE_SCRIPT" ]; then
bash "$ARCHIVE_SCRIPT" save "$wt_path" 2>/dev/null || true
fi
if git worktree remove "$wt_path" 2>/dev/null; then
rm -f "$lockfile" # Clean up lockfile (SPEC-247 AC3)
bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" worktree remove "$wt_path" 2>/dev/null || true
echo "Auto-removed (ready_for_cleanup): $wt_path"
fi
done
Operator confirmation for safe orphans
Only offer orphans with reason="safe to remove" for removal. For each safe orphan:
removed_worktrees=()
for candidate in "${orphan_candidates[@]}"; do
wt_path="${candidate%%|*}"
wt_branch="${candidate##*|}"
echo "> Remove orphan worktree $wt_path ($wt_branch)? [y/N]"
read -r response
if [ "$response" = "y" ] || [ "$response" = "Y" ]; then
# Archive session.json before deletion (SPEC-248)
if [ -f "$ARCHIVE_SCRIPT" ]; then
bash "$ARCHIVE_SCRIPT" save "$wt_path" 2>/dev/null || true
fi
if git worktree remove "$wt_path" 2>/dev/null; then
removed_worktrees+=("$wt_path|$wt_branch")
# Clean up lockfile if present (SPEC-247 AC3)
lock_branch="${wt_branch##*/}"
rm -f "$REPO_ROOT/.agents/worktrees/${lock_branch}.lock" 2>/dev/null || true
# Clear the bookmark from session.json
bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" worktree remove "$wt_path"
echo "Removed: $wt_path"
else
echo "ERROR: Failed to remove $wt_path — skipping bookmark cleanup"
fi
fi
done
Safety rules (SPEC-233 AC1-AC3, AC7)
- Current directory: Never offer for removal. Flag as
reason="current directory". - Uncommitted changes: Never offer for removal. Flag as
reason="uncommitted changes". - Unmerged branch: Never offer for removal. Flag as
reason="branch not fully merged". - Trunk: Never offer for removal. Always show as
protected: <repo_root> (trunk). - Confirmation required: Always prompt operator. Never auto-remove.
Step 2 — Git dirty-state check
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
cd "$REPO_ROOT"
git_status=$(git status --porcelain 2>/dev/null)
if [ -n "$git_status" ]; then
echo "WARN: Dirty git working tree — uncommitted changes detected."
echo "Changes:"
echo "$git_status" | head -20
else
echo "OK: Working tree is clean."
fi
Report findings with an actionable recommendation.
Step 3 — Completion pipeline check (SPEC-258)
Before proceeding to ticket sync, verify that the completion pipeline ran for any finished work in this worktree. If steps were missed, run them now.
3a — Detect pipeline state
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
STATE_FILE="$REPO_ROOT/.agents/completion-state.json"
SWAIN_TEST="$REPO_ROOT/.agents/bin/swain-test.sh"
If completion-state.json exists: read it and find incomplete steps:
PENDING_STEPS=$(jq -r '.steps | to_entries[] | select(.value.status == "pending" or .value.status == "failed") | .key' "$STATE_FILE" 2>/dev/null)
SPEC_ID=$(jq -r '.spec_id // empty' "$STATE_FILE" 2>/dev/null)
- If
PENDING_STEPSis empty → all steps passed or were skipped. Display "Completion pipeline: all steps done." and proceed. - If
PENDING_STEPSis not empty → display which steps need attention and run them (see 3b).
If completion-state.json does not exist: check whether the worktree has closed tasks:
export PATH="$REPO_ROOT/.agents/bin:$PATH"
CLOSED_COUNT=$(ticket-query '.status == "closed"' 2>/dev/null | wc -l | tr -d ' ')
- If
CLOSED_COUNT > 0→ work was done but the pipeline never started. Create the state file with all stepspendingand run them:# Try to find the SPEC ID from the plan epic EPIC_ID=$(ticket-query '.type == "epic"' 2>/dev/null | head -1 | jq -r '.id // empty') SPEC_ID=$(tk show "$EPIC_ID" 2>/dev/null | grep -i 'external_ref' | awk '{print $NF}') mkdir -p "$REPO_ROOT/.agents" jq -n --arg spec "${SPEC_ID:-unknown}" --arg branch "$(git branch --show-current)" \ '{spec_id: $spec, branch: $branch, pipeline_started: (now | todate), steps: {bdd_tests: {status: "pending", timestamp: null, detail: null}, smoke_test: {status: "pending", timestamp: null, detail: null}, retro: {status: "pending", timestamp: null, detail: null}}}' \ > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE" - If
CLOSED_COUNT == 0→ no finished work, skip this step silently.
3b — Run missing steps
For each step in the pipeline order (bdd_tests → smoke_test → retro), check its status. Skip steps that are passed or skipped. Run steps that are pending or failed.
bdd_tests:
BDD_STATUS=$(jq -r '.steps.bdd_tests.status' "$STATE_FILE")
If BDD_STATUS is pending or failed:
If
swain-test.shexists:BDD_OUTPUT=$(bash "$SWAIN_TEST" --artifacts "$SPEC_ID" 2>&1) BDD_EXIT=$?- Exit 0 → update to
passedwith detail from first 5 lines of output. - Non-zero → update to
failedwith detail from last 10 lines. Ask: "BDD failed. retry, skip, or abort?"- retry → re-run this step
- skip → set to
skippedwith detail "operator skipped during teardown" - abort → stop teardown entirely, do not proceed to sync
- Exit 0 → update to
If
swain-test.shdoes not exist: set toskippedwith detail "swain-test.sh not available". Display warning.
Use the atomic jq update pattern from DESIGN-018 for all state writes:
jq --arg step "$STEP" --arg status "$STATUS" --arg detail "$DETAIL" \
'.steps[$step].status = $status | .steps[$step].timestamp = (now | todate) | .steps[$step].detail = $detail' \
"$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
smoke_test:
If pending or failed:
If
swain-test.shexists: extract the## SMOKEsection from swain-test output and present to the operator. Ask: "Did the smoke test pass? (yes / no / skip)"- yes → set to
passedwith detail "operator confirmed during teardown" - no → set to
failed. Ask: "retry, skip, or abort?" - skip → set to
skippedwith detail "operator skipped during teardown"
- yes → set to
If
swain-test.shdoes not exist: set toskippedwith detail "swain-test.sh not available".
retro:
If pending or failed:
Invoke swain-retro using the Skill tool:
Use the Skill tool: invoke
swain-retrowith args:"Teardown catch-up — run retro for <SPEC-ID> before sync."
- On success → set to
passedwith detail "retro captured during teardown" - On failure → ask: "Retro failed. retry or abort?" (retro cannot be skipped)
3c — Force bypass
If the operator invoked teardown with --force (detected via the invocation args containing "force" or "--force"):
# Mark all pending steps as skipped
for step in bdd_tests smoke_test retro; do
STEP_STATUS=$(jq -r ".steps.$step.status" "$STATE_FILE")
if [ "$STEP_STATUS" = "pending" ] || [ "$STEP_STATUS" = "failed" ]; then
jq --arg step "$step" \
'.steps[$step].status = "skipped" | .steps[$step].timestamp = (now | todate) | .steps[$step].detail = "operator forced bypass"' \
"$STATE_FILE" > "$STATE_FILE.tmp" && mv "$STATE_FILE.tmp" "$STATE_FILE"
fi
done
Display: "Force bypass — all pending pipeline steps marked as skipped." Proceed to Step 4.
3d — Pipeline gate
After running or skipping all steps, verify:
REMAINING=$(jq -r '.steps | to_entries[] | select(.value.status == "pending" or .value.status == "failed") | .key' "$STATE_FILE")
- If empty → proceed to Step 4
- If not empty → teardown is blocked. Display which steps remain and stop.
Step 4 — Ticket sync prompt (SPEC-234 AC3, renumbered from Step 3)
Always run this step. Note degraded state if no active session:
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
session_check=$(bash "$REPO_ROOT/.agents/bin/swain-session-check.sh" 2>/dev/null)
session_status=$(echo "$session_check" | jq -r '.status // "none"')
If session_status is not "active":
- If
--session-chainwas passed, proceed anyway (caller already confirmed). - Otherwise, inform the operator: "No active session. Run
/swain-initto start one, or proceed with cleanup only?" If they proceed, skip Steps 1-2 (digest/retro need session state) and jump to Step 3 (merge).
Step 1 — Session digest
Generate the session digest while the session is still active.
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
SESSION_ID="$(jq -r '.session_id // empty' "$REPO_ROOT/.agents/session-state.json" 2>/dev/null)"
if [ -n "$SESSION_ID" ]; then
bash "$REPO_ROOT/.agents/bin/swain-session-digest.sh" \
--session-id "$SESSION_ID" \
--output "$REPO_ROOT/.agents/session-log.jsonl" 2>/dev/null
fi
If the digest script is missing or fails, log a warning and continue. The digest is useful but not blocking.
Step 2 — Retro (session still active)
Critical: The session must still be active when retro runs so it can read session state. Do not close the session before this step.
Invoke swain-retro:
Skill("swain-retro", "Session is closing. Run retro to capture learnings before session state is cleared.")
If swain-retro is not available, log "Retro skill not found — skipping" and continue. The shutdown sequence must not fail because a skill is missing.
Step 3 — Merge worktree branches
For each active worktree (excluding trunk), offer to merge its branch into trunk. This is the step that was missing from the old teardown — without it, worktrees could never be "safe to remove" because their branches were never merged.
3.1 — Enumerate worktrees
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
TRUNK=$(bash "$REPO_ROOT/.agents/bin/swain-trunk.sh" 2>/dev/null || echo "trunk")
git worktree list --porcelain 2>/dev/null | grep "^worktree " | while read -r line; do
wt_path="${line#worktree }"
# Skip trunk
[ "$wt_path" = "$REPO_ROOT" ] && continue
wt_branch="$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null)"
echo "$wt_path|$wt_branch"
done
3.2 — Triage each worktree
For each worktree, classify its state:
| State | Condition | Action |
|---|---|---|
| Already merged | git merge-base --is-ancestor "$wt_branch" "$TRUNK" |
Skip merge, mark safe for cleanup |
| Clean, unmerged | No uncommitted changes, branch not merged | Offer merge |
| Dirty | git -C "$wt_path" status --porcelain has output |
Warn operator, offer to commit first |
| Current directory | "$wt_path" = "$(pwd)" |
Must exit first via ExitWorktree |
3.3 — Merge unmerged branches
For each "clean, unmerged" worktree, ask the operator:
Worktree
{path}(branch{branch}) has unmerged changes. Options:
- Merge — merge branch into {trunk} now
- PR — push branch and create a pull request
- Skip — leave branch as-is (worktree will be preserved)
If merge:
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
TRUNK=$(bash "$REPO_ROOT/.agents/bin/swain-trunk.sh" 2>/dev/null || echo "trunk")
# Link safety — scan for worktree-specific path links before merging
DETECT_SCRIPT="$REPO_ROOT/.agents/bin/detect-worktree-links.sh"
RESOLVE_SCRIPT="$REPO_ROOT/.agents/bin/resolve-worktree-links.sh"
if [ -x "$DETECT_SCRIPT" ]; then
MERGE_BASE=$(git -C "$wt_path" merge-base HEAD "origin/$TRUNK" 2>/dev/null || true)
CHANGED_FILES=$([ -n "$MERGE_BASE" ] && git -C "$wt_path" diff --name-only "$MERGE_BASE" HEAD 2>/dev/null || true)
if [ -n "$CHANGED_FILES" ]; then
if ! echo "$CHANGED_FILES" | xargs "$DETECT_SCRIPT" --repo-root "$REPO_ROOT" > /dev/null 2>&1; then
echo "[link-safety] Found suspicious links in $wt_branch. Resolving..."
echo "$CHANGED_FILES" | xargs "$RESOLVE_SCRIPT" --repo-root "$REPO_ROOT" 2>/dev/null || true
fi
fi
fi
# Merge into trunk from the main worktree
cd "$REPO_ROOT"
git fetch origin 2>/dev/null
git merge "$wt_branch" --no-edit
If the merge has conflicts, report them to the operator and skip this worktree. Do not force-resolve.
If PR:
cd "$wt_path"
git push -u origin "$wt_branch" 2>/dev/null
SUBJECT=$(git log -1 --pretty=format:'%s')
gh pr create --base "$TRUNK" --head "$wt_branch" --title "$SUBJECT" --body "Teardown PR — branch from session teardown."
Report the PR URL.
If skip: Mark the worktree as preserved. It will not be removed in Step 4.
3.4 — Handle "current directory" worktree
If the operator is currently inside a worktree, handle it last. After all other worktrees are processed:
- Ask if they want to merge this branch too (same options as 3.3).
- If merge or PR: commit any uncommitted changes first, then call
ExitWorktreeto return to trunk. - If skip: call
ExitWorktreewithaction: "keep"to preserve the branch.
Step 4 — Worktree cleanup
After merges, clean up worktrees whose branches are now merged.
4.1 — Re-enumerate and check merge status
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
TRUNK=$(bash "$REPO_ROOT/.agents/bin/swain-trunk.sh" 2>/dev/null || echo "trunk")
git worktree list --porcelain 2>/dev/null | grep "^worktree " | while read -r line; do
wt_path="${line#worktree }"
[ "$wt_path" = "$REPO_ROOT" ] && continue
wt_branch="$(git -C "$wt_path" rev-parse --abbrev-ref HEAD 2>/dev/null)"
# Safety checks
if [ "$wt_path" = "$(pwd)" ]; then
echo "SKIP: $wt_path — current directory"
continue
fi
if [ -n "$(git -C "$wt_path" status --porcelain 2>/dev/null)" ]; then
echo "SKIP: $wt_path — uncommitted changes"
continue
fi
if ! git merge-base --is-ancestor "$wt_branch" "$TRUNK" 2>/dev/null; then
echo "SKIP: $wt_path — branch not merged"
continue
fi
echo "SAFE: $wt_path|$wt_branch"
done
4.2 — Remove safe worktrees
For each SAFE worktree, remove it without asking. The branch is merged, there are no uncommitted changes, and it is not the current directory. The operator already approved the merge in Step 3.
git worktree remove "$wt_path" 2>/dev/null && echo "Removed: $wt_path ($wt_branch)"
# Clear bookmark
bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" worktree remove "$wt_path" 2>/dev/null
If removal fails, report and continue.
4.3 — Prune stale worktree references
git worktree prune 2>/dev/null
bash "$REPO_ROOT/.agents/bin/swain-bookmark.sh" worktree prune 2>/dev/null
Step 5 — Close session state
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
WALKAWAY_NOTE="${WALKAWAY:-Session closed via teardown}"
bash "$REPO_ROOT/.agents/bin/swain-session-state.sh" close \
--walkaway "$WALKAWAY_NOTE" \
--session-roadmap "$(pwd)/SESSION-ROADMAP.md" 2>/dev/null
The walkaway note should summarize what was accomplished. Infer from the session's work (merged branches, closed tasks, retro output) or ask the operator for a one-liner.
Step 6 — Commit handoff
Stage and commit any session artifacts that changed during teardown.
REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
# Stage session artifacts
git add SESSION-ROADMAP.md 2>/dev/null
git add docs/swain-retro/ 2>/dev/null
git add .agents/session-state.json 2>/dev/null
git add .agents/session-log.jsonl 2>/dev/null
# Check if there's anything to commit
# Resolve model name from the system prompt. When subagents ran under a
# different model, include one Co-Authored-By trailer per model (see
# AGENTS.md Model attribution).
if [ -n "$(git diff --cached --name-only 2>/dev/null)" ]; then
git commit -m "chore: session teardown handoff
Co-Authored-By: <model-name-from-system-prompt> <noreply@unknown>"
fi
Summary report
After all steps, display a summary:
=== Session Teardown Complete ===
Retro: {fired / skipped / not available}
Branches: {N merged, M PRs created, K preserved}
Worktrees: {N removed, M preserved}
Session state: closed
Handoff commit: {hash or "nothing to commit"}
Exit with code 0 unless a critical error occurred.
Error handling
| Situation | Response |
|---|---|
| No active session (without --session-chain) | Offer cleanup-only mode (Steps 3-4), skip digest/retro |
| Digest script missing | Warn and continue |
| Retro skill missing | Warn and continue |
| Merge conflict | Report conflicting files, skip that worktree |
| Worktree removal fails | Report and continue |
| Session state script missing | Warn, skip close |
| Nothing to commit in Step 6 | Report "clean" and exit |
| Git unavailable | Fatal — cannot proceed |
Integration
Called from swain-init (decision budget)
When the decision budget is reached during a session, swain-init can invoke teardown:
Skill("swain-teardown", "Decision budget reached. Run teardown sequence.")
Called from meta-router
The swain meta-router routes "done", "wrap up", "close session", "teardown" to this skill.
Standalone invocation
The operator can run /swain-teardown at any time. If no session is active, it offers cleanup-only mode.