Call at the BEGINNING of every work session on a project.

Returns a session_id to pass in all subsequent log_agent_event calls so Threadline can group events into a coherent session.

Returns

dict with keys: session_id, project_key.

Call at the END of a work session to close it cleanly.

Records a session_ended event so the next agent can see what was done.

Returns

dict with keys: session_id, status, project_key.

Report a work event to Threadline — call this as you work.

Parse and ingest a single AgentEventIn JSON payload. Returns a summary of what was derived (decision count, open-loop count).

WHEN TO CALL

• At significant checkpoints (code written, tests passing, a decision made).

• When you encounter a blocker.

• When you notice something deferred (open loop).

EVENT SHAPE (compact example)

{
  "event_type": "checkpoint",
  "project_key": "my-project",
  "agent": {"name": "claude_code"},
  "session_id": "<from start_session>",
  "summary": "Implemented login route; all tests pass.",
  "details": {
    "decisions": ["Use JWT over session cookies for stateless auth"],
    "open_loops": ["Rate limiting not yet implemented"],
    "files_changed": ["src/auth.py", "tests/test_auth.py"],
    "verification": ["uv run pytest -q"]
  }
}

Returns

dict with keys: event_id, session_id, decisions_created, open_loops_created. On parse/validation error: {"error": true, "message": "..."} — fix and retry.

Return the raw governed state for a project.

Returns durable lifecycle records only — no synthesis, no compiled memory, no LLM output, no ranking.

Includes: objective, open loops, active decisions, known traps, confirmed gaps and caveats, evidence IDs, recent session metadata.

Returns

dict — the full ProjectState as a plain dict.

Raises

LookupError if the project does not exist (surfaced as an error dict).

Return open loops for a project, oldest first.

Open loops are deferred threads — things noticed but not finished. Oldest-first because the longest-waiting item is most likely blocking.

Filters (all optional, combinable):

• owner: only loops claimed by this owner (pass "unassigned" to get loops with no owner — the claimable set)

• lane: only loops tagged with this lane (e.g. retention-b)

• claimable: True = owner is NULL; False = owner is set

Returns

list of dicts with keys: id, description, project_key, status, owner, lane, created_at, updated_at.

Mark an open loop resolved — GATED: requires admissible evidence.

Evidence refs must be '<kind>:<id>' strings pointing to records that independently verify the loop is done. Self-reference is rejected.

Returns

dict with keys: id, status, resolved_at.

Claim an open loop for an owner — FIRST CLAIM WINS.

The foreman and every agent must claim a loop BEFORE touching files. A loop is claimable while owner is unset; the first claim wins. Re-claiming by the same owner is a no-op. Claiming someone else's loop raises an error and returns the current owner in the message.

Returns

dict with keys: id, status, owner, lane.

Return the LIVE decisions for a project, newest first.

Live = status in (active, accepted, validated). Decisions marked incorrect/reverted are returned by get_known_traps instead.

Returns

list of dicts with keys: id, statement, rationale, status, created_at.

Return one decision + its outcome detail, or an error dict if not found.

Returns

dict with keys: id, statement, rationale, status, created_at, outcome (the detail dict or None).

Record the real-world OUTCOME of a past decision.

outcome must be one of: accepted, validated, incorrect, reverted, unresolved.

HARD RULE: marking incorrect/reverted/validated requires admissible evidence_refs — records that independently back the outcome. Self-certification is rejected. An operator may override via the CLI.

Returns

dict with keys: id, decision_id, outcome, status, severity, evidence_refs, superseded, marked_at.

Return decisions proven wrong on this project + the corrected rule.

Read these BEFORE acting so you do not repeat a known mistake. Newest first; each carries the corrected_rule (the lesson), severity, and evidence_refs.

Returns

list of dicts with keys: decision_id, statement, outcome, corrected_rule, severity, evidence_refs, marked_at.

Propose a gap or caveat finding.

PROPOSING IS FREE — a proposed finding is never surfaced in the trusted context bundle. It is a candidate until confirmed with evidence.

finding_class ∈ {gap, caveat}. severity ∈ {low, medium, high, critical}.

Fingerprint dedup: re-proposing an active finding returns the existing id (no duplicate write).

Returns

dict with keys: finding_id, status, finding_class, category, statement, severity.

Confirm a proposed finding so it enters the trusted bundle.

GATED: requires evidence_refs pointing to independently evidence-bearing records. A bare assertion, another finding, or a self-referential loop is rejected.

Returns

dict with keys: finding_id, status, confirmed_at.

Mark a finding resolved (its resolution_condition was met).

GATED exactly like confirm_finding.

Returns

dict with keys: finding_id, status, resolved_at.

Dismiss a finding as invalid/irrelevant.

GATED exactly like confirm_finding.

Returns

dict with keys: finding_id, status, dismissed_at.

Resolve evidence refs ('<kind>:<id>') to bounded content snippets.

Returns bounded snippets only — never full transcript bodies. Bad refs are reported in unresolved without failing the whole call.

Returns

dict with keys: evidence (list), unresolved (list), truncated_refs (list).

Full-text search across all stored memory.

Searches events, decisions, open loops, daily notes, and compiled context fragments. Results are ranked by BM25 relevance.

Parameters

query: Natural-language search string. project_key: When provided, restricts results to that project. limit: Maximum results to return (clamped to 50 server-side).

Returns

list of dicts with keys: kind, ref_id, project_key, title, snippet.