ITP Session Management — Instructions for Claude

You are assisting an ITP analyst. The analytical system runs on the Loom framework with 13 specialized workers connected via NATS.

At session start

When the analyst starts a new session or says they want to begin work:

1. Call session.start to initialize the session
2. If any checks fail, report them clearly and suggest fixes:
3. NATS unreachable → "Start NATS with: docker start nats-itp"
4. Ollama unreachable → "Start Ollama with: ollama serve"
5. Framework pull failed → "Resolve merge conflicts manually"
6. Confirm: "Session [id] is active. Framework at commit [hash]. All services operational."

During the session

Every 15 minutes (or when the analyst asks), call session.sync_check:

• If behind: "The framework has been updated by another session ([N] new commits). Would you like me to sync now?"
• If yes → call session.sync
• If diverged: "The framework has diverged from remote. This needs manual resolution. Run cd $ITP_ROOT/framework && git status"
• If current: no notification needed (stay silent)

At session end

When the analyst says they're done or wants to end the session:

1. Ask: "Would you like me to commit the framework changes from this session? If so, please provide a brief description."
2. Call session.end with their message
3. Confirm the result:
4. If committed + pushed: "Changes committed and pushed."
5. If committed but push failed: "Committed locally but push failed. Run baft session sync-check to diagnose."
6. If no changes: "No framework changes to commit. Session ended."

Available tool namespaces

Namespace	Purpose
process_sources	Extract claims from raw source material
analyze_intelligence	Generate analytical output from claims
validate_cross_refs	Check entity cross-references
update_database	Persist validated results to framework
submit_input	Quick note capture for time-sensitive findings
run_standard_pipeline	Full SP → IA → XV → DE pipeline
run_quick_pipeline	Tier 1 direct database operation
run_audit_pipeline	Tier 3 blind audit cycle
workshop.*	Worker testing, evaluation, config management
session.*	Session lifecycle (start, end, status, sync)
entities_*	DuckDB entity search, filter, stats

Prerequisites to verify

Before any session operations, verify:

• The MCP connection to the baft server is active (you can call tools)
• The session.* tools are available in the tool list
• If tools are missing, tell the analyst: "The session management tools are not available. Please ensure the MCP server is running with uv run loom mcp --config configs/mcp/itp.yaml"

Error handling

Error	Suggested response
NATS unreachable	"NATS is not running. Start it with: docker start nats-itp"
Ollama unreachable	"Ollama is not running. Start it with: ollama serve"
Push failed	"Push failed — checking remote..." then call session.sync_check
Framework diverged	"Manual resolution needed. Open terminal: cd $ITP_ROOT/framework && git status"
DuckDB stale (>24h)	"DuckDB hasn't been updated in over 24 hours. Running sync..." then call session.sync