pi-closeout

Session closeout gate for coding agents: catch the loose ends a work session leaves behind before they become someone else's incident.

On a shared checkout, the session that ends dirty sets up the next session's failure: staged-but-uncommitted files get swept into whoever commits next; untracked evidence gets eaten by the next stash cycle; unclaimed task lines go stale and block the board. pi-closeout makes "how did this session end?" a checkable, persisted fact.

Install it if more than one session ever works in the same checkout, or if you have been bitten by a commit that silently absorbed someone else's staged file.

Install

pi install npm:pi-closeout

Then restart pi (or /reload). Zero-config in any git repository.

From a local checkout:

pi install ./pi-closeout
pi -e ./pi-closeout/extensions/closeout.ts

Quick start

When the session ends — or when you ask:

$ /closeout
2 finding(s)

session closeout — /repo
  identity: Work-Session: 01a2b3c4-56af-75c8-a90d-2a0359a79cbc
  ✓ nothing staged
  ✓ clean root tree
  ✓ child repos clean (or none present)
  ✗ [untracked] untracked files (stash-cycle bait — commit, move, or own them):
    evidence/r4-fails-on-main.txt
  ✗ [claim] open claims in TASKS.md (resolve or re-claim):
    3: - fix pagination — claimed @alice 2026-10-18
session-closeout: 2 finding(s)

Clean checks print as ✓ notes, informational ones (a modified-but-uncommitted root tree) as • notes, findings as ✗ [kind]. A clean run ends session-closeout: clean.

--strict throws on findings instead of reporting them, for script and CI use. The shutdown gate runs the same checks once at session end, best-effort, and records the count in the registry so "closed with N loose ends" is greppable history. It never blocks shutdown.

What it does

Work-Session trailers

Some host setups stamp every commit with an advisory Work-Session: <session-id> trailer (via a prepare-commit-msg hook), so later provenance queries can attribute commits to sessions. On detached or edge commit paths the injection can miss, and the gap only surfaces when those queries come up empty. The gate flags recent commits missing the trailer — the 10 most recent, plus an overflow count.

Detection is automatic and quiet: it inspects the last 30 commits, and if none carries a Work-Session trailer the convention is treated as not in use and the check emits nothing at all — repos that never adopted it get zero extra output. Where the convention is in use, "auto" only looks at commits newer than the newest trailer-bearing commit: history from before adoption (init, first imports) is not a gap, and flagging it buried the one real miss in a wall of pre-convention noise.

Configuration (.pi-closeout.json)

Optional, at the repo root:

{
  "claimsFiles": ["TASKS.md"],
  "claimPattern": "— claimed @",
  "childRepos": true,
  "checkStaged": true,
  "checkUntracked": true,
  "ignoreUntracked": [".session-registry.jsonl", ".pi-closeout.jsonl", ".pi-closeout.json"],
  "registry": "auto",
  "checkWorkSessionTrailer": "auto"
}

Disable entirely with CLOSEOUT_DISABLE=1. Set WORK_SESSION to force the identity string (any harness).

Claude Code wiring

{ "hooks": { "Stop": [{ "hooks": [{ "type": "command",
  "command": "bash /path/to/session-closeout.sh" }] }] } }

Registry rows

{"ts":1730000000000,"type":"identity","name":"alice","pid":4242,"identity":"01a2b3c4-56af-75c8-a90d-2a0359a79cbc"}
{"ts":1730000600000,"type":"closeout","name":"alice","pid":4242,"identity":"01a2b3c4-56af-75c8-a90d-2a0359a79cbc","ok":true,"findings":2}

How this differs from neighbors

Static hygiene hooks lint the tree on every command; pi-closeout is lifecycle-scoped — it fires when a session ends (or on demand), grades findings by how they hurt the next session, and persists a per-session closeout row. Pair it with pi-checkout-guard (which guards concurrent mutations) for full shared-checkout hygiene: guard = during, closeout = after.

Scope and non-goals

• Not a linter. It does not judge what is staged or untracked — only that something is, and how that hurts the next session.
• Not a fixer. It never stashes, commits, or deletes on your behalf.
• Never blocks. Findings are reported (and recorded); shutdown is not interrupted. Use --strict where a pipeline wants a non-zero exit.
• Convention-aware, not convention-enforcing. Claims and Work-Session: trailers are your conventions: nothing is flagged until the file or the trailer exists in the repo.

Requirements

No network access, no telemetry, no runtime dependencies beyond pi's own packages.

Troubleshooting

It reports the registry as an untracked file. It should not: the fallback registry lives inside .git/. If you configured "registry" with a path inside the worktree, add that path to ignoreUntracked.

Trailer findings for commits I made before adopting the convention. Set checkWorkSessionTrailer: "false" to disable, or rely on "auto", which only looks at commits newer than the newest trailer-bearing one — and stays silent entirely in repos that never adopted the trailer.

Claim findings for a task file I don't use. Point claimsFiles at your own board (any file), or clear the array to disable the check.

/closeout reports a dirty child repo I don't own. Nested repos are checked to depth 2; set childRepos: false when a vendored repo is out of scope.

Related packages

Five extensions for the same problem — agent sessions sharing a checkout — covering different moments:

Development

npm install
npm run typecheck
npm test

License

MIT © jyyyeung