lemurOS:close-session

lemurOS:close-session

When to use

• The SessionEnd hook fires and emits a context message asking you to close the open session.
• The user types "wrap up" / "close the session" / "we're done for tonight".
• You have authored >=1 spec in <project>/docs/specs/ or advanced any plan in <project>/docs/plans/ and want the vault mirror updated now.

When NOT to use

• There is no vault/projects/<slug>/sessions/<sessionId>.md with status: open — there is no session to close.
• You are in a non-LemurOS-managed repo (no entry in vault/_registry.json for the cwd).

Hard gates

Dispatch the Librarian — never write to `vault/projects//sessions/` or `vault/projects//{specs,plans}/` directly. The `sessionId` MUST match the open session's frontmatter `id` field. If you cannot find an open session, emit `BLOCKED` with the path you searched. Every entry in `plansAdvanced` MUST correspond to a real file under `/docs/plans/`. If a path cannot be resolved, emit `BLOCKED`.

Steps

1. Discover the open session. Glob vault/projects/<slug>/sessions/*.md (or read the SessionStart hook's emitted path). Read frontmatter; confirm status: open. Extract id.
2. Gather the deltas. Read the in-session conversation context for: tasks whose status changed (from lemurOS:update-task-status invocations); decisions logged (from lemurOS:log-decision calls); spec files authored under <project>/docs/specs/; plan files whose checklist count changed under <project>/docs/plans/.
3. Compute plansAdvanced. For each plan touched, count - [x] and - [ ] lines to derive stepsCompleted and stepsTotal. Use a single Bash invocation like pnpm exec node -e "..." or read each file and tally — do not skip.
4. Build the WriteRequest. Envelope = {operation: "close-session", slug, rationale: "session wrap-up", agent: "<your agent name>", payload: {...}}. Validate locally with the same WriteRequestSchema.parse one-liner used by lemurOS:register-project.
5. Dispatch the Librarian via the Task tool, subagent_type: lemurOS-librarian.
6. Handle the response — same five cases as register-project:
   • ok: true — report SHA + verdict DONE.
   • SCHEMA_INVALID — fix payload, retry once. If it fails again, emit ESCALATE.
   • PATH_FORBIDDEN — emit ESCALATE with the librarian's message quoted.
   • CONCURRENT_WRITE — wait 2s, retry up to twice; if still failing, ESCALATE.
   • IO_ERROR — emit BLOCKED; do not retry.

Worked example

A session closing one task transition, one decision, one spec, and one plan with 7/20 steps done in project demo, session 2026-05-12-2330:

{
  "operation": "close-session",
  "slug": "demo",
  "rationale": "session wrap-up",
  "agent": "lemurOS-backend-dev",
  "payload": {
    "sessionId": "2026-05-12-2330",
    "summary": "Implemented T-014 (token refresh) end-to-end. One decision logged on cookie storage; spec for the refresh flow authored.",
    "tasksTransitioned": ["T-014"],
    "decisionsLogged": ["2026-05-12-cookie-storage"],
    "specsAuthored": ["docs/specs/2026-05-12-token-refresh.md"],
    "plansAdvanced": [
      { "path": "docs/plans/2026-05-12-token-refresh.md", "stepsCompleted": 7, "stepsTotal": 20 }
    ]
  }
}

Expected Librarian success response:

{
  "ok": true,
  "paths": [
    "vault/projects/demo/sessions/2026-05-12-2330.md",
    "vault/projects/demo/specs/2026-05-12-token-refresh.md",
    "vault/projects/demo/plans/2026-05-12-token-refresh.md"
  ],
  "commitSha": "<40-char SHA>"
}

Trade-off (Phase 3 resolution)

Specs and plans are written directly by the authoring skills (lemurOS:brainstorming, lemurOS:writing-plans, lemurOS:executing-plans) to the project working tree (architecture §8.10 makes that tree user/agent-writable, so invariant 2 is not violated — only the vault mirror is under the Librarian's exclusive control). The vault mirror at vault/projects/<slug>/{specs,plans}/ is updated only by this skill (at session end) or by /lemur-os:sync (on demand). A session crash before close lags the vault mirror by one session — recoverable by re-dispatching this skill or running /lemur-os:sync.

What this skill must NEVER do

• Write to vault/ or vault/projects/<slug>/ directly.
• Open a new session — that is the SessionStart hook's job.
• Mirror specs/plans for a slug different from the current session's slug.
• Skip the schema-validation step before dispatch.

Verdict

• DONE on Librarian ack with ok: true.
• BLOCKED on IO_ERROR or when no open session can be found.
• ESCALATE on persistent PATH_FORBIDDEN or repeated SCHEMA_INVALID.