Work sessions

A work session is one human intent — "implement CLAIM-142". It is opened by a coding agent through the MCP, closed by the agent or by a person, and everything in between is recorded against it.

Workspace → Work sessions.

Nothing here starts one

A session opens when a coding client calls madebook_session_start through the MCP server. Nothing here starts one — this is where you watch them.

Three things can open one:

1. The model calls madebook_session_start.
2. The client's SessionStart hook opens it before the model does anything.
3. On Cursor, which has no session-start event, it opens on the first turn that ends.

What has to be true before one opens

Registration is gated, in this order:

1. You must hold session.register — owner, admin or member.
2. The workspace must exist.
3. The coding client must be approved by your organization. An unapproved client is refused with CLIENT_NOT_APPROVED — before it is briefed with anything.
4. If a mission is named, its contract must be approved. Otherwise: "{reference} has a draft contract (v{n}). A lead approves it on the Missions page before an agent can start on it."

Resuming rather than duplicating

A client reconnecting with the same external id resumes the session rather than opening a second one. The timeline records "Session reconnected."

A crashed-and-restarted agent is one session with a gap, not two — and modelling it as two would invent a phantom collision between an agent and its own earlier self.

Statuses

Status	Meaning
starting	Registered, not yet briefed.
working	Set automatically on the first brief, and again whenever a change is reported — a session that is reporting changes is working, whatever it last said about itself.
blocked	The agent said it is stuck.
awaiting_review	It reported implementation complete. Progress is forced to 100.
paused	A person pulled the brake.
complete / failed	Ended.

A session is treated as live while it is starting, working, blocked, paused or awaiting review.

Note that a session's self-reported progress is advisory and never used to decide anything.

What is recorded against one

Context snapshot	What it was briefed with, by version.
AI runs	Each model invocation — provider, model, purpose, counts. Never a prompt, never an output.
Timeline events	Everything that happened, in order.
Dependencies	What it is standing on.
Change sets	What it changed, in sequence.
Evidence	What it can show for it.
Context health	Snapshots over time.
Pull request	Where it landed.

Also: the client, the branch, the worktree path, the commit it started from, the constitution and contract versions it was briefed on, and who started it.

The timeline

Every event carries a summary, an actor (agent, madebook or human) and a time. The kinds you will see:

started, resumed, briefed, changed_files, report_refused, symbols_partial, run_recorded, run_refused, plan_created, step_pending through step_blocked, decision_requested, decision_resolved, implementation_complete, pull_request_reported, remediation_requested, blocked, failed, completed, progress, paused, rebriefed.

Amber marks a block, a deviation, staleness or a pause. Red marks a failure, a collision or a refused run. Green marks completion.

How reports arrived

A session shows its own wiring: via hook, via the model's own calls, or both.

That is measured from what actually arrived, never from how the client was configured. A hook that is installed and never fires reads as "the model's own calls", which is the honest answer.

Context health

Six dimensions, each a real comparison against something recorded.

Dimension	Compared against	How it is scored
Mission understanding	Clauses added since the brief; the contract version	A version bump caps it at 50
Architecture context	The constitution version	−35 per version of drift; 0 if never briefed
Repository state	The commit it started from vs the indexed commit	Equal is 100, different is exactly 55
Requirement confidence	Open requirement ambiguities	−30 each
Dependencies current	Open collisions where this session is the affected side	−45 per high, −15 otherwise
Decisions current	Active decisions recorded after the brief	−40 each; 0 if never briefed

Repository state is 55 rather than a distance, on purpose: we know it differs, and we do not know by how much without walking history, so this reports "not current" rather than inventing a number.

The overall score is the minimum, not the average.

Health is a floor: an agent with perfect mission understanding and a stale view of the repository is not 80% healthy, it is about to do 100% of its work wrong.

A dimension that cannot be computed is blank, not 100, and it records why — for example "This session is not attached to a mission, so there is no contract to have understood." or "This workspace has no architecture constitution. Derive one from the indexed repository."

Verdict	Overall
healthy	85 or above, or nothing computable
degraded	below 85
stale	below 60

A re-brief is recommended on staleness, and on any high-severity dependency break regardless of the floor — that one is not a degradation, it is work being built on something that moved.

Health is recomputed on every brief, on resume, for every live session after any change report, and whenever you press Re-check.

Pausing

Pause needs session.control — owner, admin or member. The dialog is honest about what it can and cannot do:

Madebook cannot kill a process on someone else's machine. It tells the agent to stop the next time it checks in, with your reason, and the agent re-briefs when you let it continue.

There is no kill. The pause is pull, not push: the agent learns on its next call for context, which reports the pause and the reason and forces its next action to BLOCKED.

Resume clears the pause and, importantly, clears the brief stamp too — "Resumed. The session must re-brief before its context counts as current."

Ending

madebook_session_end closes it, or the client's session-end hook does, or it reports a failure.

On close, every open collision where this session was the affected side is closed as stale: "{label} ended before this was resolved." Then the pull request verdict is re-posted and the attention queue is swept.

The reply says it plainly:

The session is closed. Whether the mission is complete is decided by the evidence gate, the pull request and a person — not here.

A session that stopped without finishing raises an attention item at inform, urgency 30.

Related

• The brief
• The execution protocol
• Changes and review capsules
• The collision radar