session

Your objective is to manage CocoSession, the continuity and operator-control layer for long-running CocoPlus work.

Commands

• $session status: read .cocoplus/session/PROGRESS.md, .cocoplus/session/CONTEXT.md, .cocoplus/session/iteration-budget.json, .cocoplus/session/budget-state.json, .cocoplus/session/status.json, .cocoplus/pod-state.json, .cocoplus/AGENT_STOP, and .cocoplus/STEER.md; report handoff freshness, active predicate state, queued work count, iteration budget, cost-budget state, terminal status, kill-switch state, and pending steering.
• $session progress: show the four handoff sections from .cocoplus/session/PROGRESS.md: Done, In Progress, Next, Notes.
• $session steer "<instruction>": write the instruction to .cocoplus/STEER.md. The UserPromptSubmit hook injects it once, appends a session event, then clears the file.
• $session stop: create .cocoplus/AGENT_STOP with timestamp, operator, and reason. The PreToolUse hook blocks tool use while the sentinel exists.
• $session resume: remove .cocoplus/AGENT_STOP after confirming the operator intends to resume.

Continuity Contract

Every CocoFlow or long-running operator session must be recoverable from files alone:

1. .cocoplus/session/PROGRESS.md is the human handoff.
2. .cocoplus/session/CONTEXT.md is machine-greppable predicate state in CLASS.key=value form.
3. .cocoplus/session/task-queue.jsonl records mid-session requests without replacing the active item.
4. New work is queued under Next unless the operator explicitly changes the current item.
5. .cocoplus/session/iteration-budget.json tracks cap, consumed turns, warning threshold, and stop state.
6. .cocoplus/session/budget-state.json tracks normal, reserve, or exhausted cost-budget state. Budget checks happen at stage boundaries only; in-flight stages are never interrupted.
7. .cocoplus/session/status.json and .cocoplus/pod-state.json use the canonical status vocabulary: running, paused, completed, exited, failed, idle, retired.

Read PROGRESS.md before resuming any long-running work. Cite CONTEXT.md predicates verbatim; do not paraphrase them into new state.

Iteration Budget

cocoplus.toml [session] controls:

max_iterations = 200
iteration_warn_at = 160
budget_limit = 0.0
budget_reserve_fraction = 0.10
budget_enforcement = "stage-boundary"

The PostToolUse hook increments the consumed counter. At warn_at, CocoSession records a proactive checkpoint request in session/steps.jsonl. At cap, it creates .cocoplus/AGENT_STOP and writes the final budget state so the operator gets a clean handoff instead of an exhausted context window.

When budget_limit is set and budget_enforcement = "stage-boundary", cost enforcement is seam-based. The reserve fraction is protected for landing work: final quality review, console state update, and handoff notes. A budget stop is exited, not failed, unless an execution error caused it.

PROGRESS.md must include:

## Iteration Budget
Cap: 200
Consumed: 0
Warn At: 160

ctx Supplement

When ctx is available, CocoSession may read cortex ctx show all as a supplement to PROGRESS.md:

• ctx tasks in task-list state map to In Progress.
• ctx ready steps map to Next.
• ctx discoveries map to session context additions.

Hard constraints:

• Never set CTX_DIR in CocoPlus production workflows. It changes process.cwd() and can break CocoPod-relative paths.
• Set CTX_STEP_ENFORCEMENT=false for CocoFlow stage execution so ctx gates do not conflict with CocoFlow gates.
• If ctx and CocoFlow disagree about the active task, CocoFlow takes precedence.

Exit Criteria

• PROGRESS.md has Done / In Progress / Next / Notes sections.
• PROGRESS.md includes Iteration Budget when long-running work is active.
• Cost-budget state distinguishes normal, reserve, and exhausted.
• Terminal status uses the canonical vocabulary and does not collapse exited into failed.
• CONTEXT.md uses one predicate per line.
• Kill-switch and steering files are treated as operator controls, not permanent instructions.

Anti-Rationalization

Shortcut / Temptation	Why It Fails
Treat the skill as complete because the file exists	Skill contracts must describe observable behavior and verification, not just command names.
Skip artifact and safety checks for a small command	Small commands still mutate state or guide execution; preserve the same gates.