Contextq MCP

Open a fan-out RUN and mint the id every agent in it shares. The ORCHESTRATOR calls this once before spawning, then pastes the returned run_id into each agent's prompt alongside the other pinned contracts. Registering the run is what lets an empty findings read mean "nobody has found anything yet" instead of "you were left out". Idempotent: re-opening the same id returns the existing record.

End or update an agent session's status. Use status='completed' when the goal is met, 'paused' to suspend (resume later from the checkpoint), 'stalled' when the vibe-loop stall detector trips, or 'abandoned' to drop the run. Setting completed/abandoned stamps ended_at.

Start a new agent session (a run with a goal). Returns the created session including its id. Use when beginning a fresh task that you want to track and resume. Pass parent_session_id to chain a resumed run to its predecessor.

Find already-distilled, parametrized procedures matching a goal (T376). A scheduled job clusters repeated, independently-verified agent_task successes (by goal similarity + tool-call-sequence shingling) into type='procedure' contexts with literal args lifted to {{placeholders}} and lineage back to their source sessions/tasks. Returns {suggestions:[{context_id, name, description, success_count, similarity}]} — fetch the full procedure with ctx_get(context_id) before starting work on a matching goal, instead of re-deriving a solution from scratch. `similarity` is null when no embedding provider …

Flip a task's status. Setting status='verified' REQUIRES non-empty `evidence` (real observed output: test result, HTTP status, exit code) — the no-self-certification rule. Returns 400 if you try to verify without evidence. Use this as each checklist item is proven. Trigger: user reports finishing a piece of tracked work ("xong rồi", "xong X", "done X", "done", "mark done", "finished X") — tick the matching session-scoped checklist item here (use goal_advance instead for a board-level task). Only call when it maps to a tracked item; ignore unrelated casual chatter.

Create or update one checklist item in a session's task tree. Omit task_id to create; pass task_id to update. `verify_cmd` names HOW the item is proven done (the agent must run it before ticking). Use parent_task_id for subtasks. This productizes the vibe goal-file checklist. Trigger: call at the START of a tracked piece of work to record a checklist item (session-scoped — for a task meant to persist across sessions use goal_add on the board instead). Only call when the work is actually being tracked; ignore unrelated casual chat.

Inspect the in-process LLM job queue. Returns `{pending, running, completed, failed, rejected, capacity:{concurrency, maxPending}, enabled}`. Counters reflect a single API instance because the queue is in-process. Use after a burst of writes or 429s from a provider to confirm the queue is not saturated. Superadmin scope only.

Inspect the in-memory per-tenant rate-limit buckets. Returns one row per tenant currently tracked by the limiter (tenant_id, tenant_slug, tokens remaining, capacity, refill_per_min). The bucket map lives in process memory, so the snapshot reflects only the API instance that handled the request. Useful for ops triage when a tenant is reporting 429s. Superadmin scope only.

Override the per-tenant rate limit. Patches `tenants.settings.rate_limit` with the provided fields and invalidates the cached bucket so the new config takes effect on the tenant's next request. Defaults are 600 capacity / 600 refill per minute. At least one of capacity or refill_per_min must be provided. Superadmin scope only.

Verify the per-row sha256 chain of activity_logs. Returns `{ok: true, total_checked}` when intact, or `{ok: false, broken_at_id, total_checked}` when a row's prev_hash mismatches the previous row's row_hash. Accepts `prev_hash=''` as valid chain-restart genesis (see migration 0029 + PR #157). Superadmin scope only.

Manually trigger one pass of the audit log retention cleaner. Deletes rows from activity_logs whose created_at is older than retention_days (capped at the AUDIT_LOG_RETENTION_DAYS env default when omitted; floor of 7 days is always enforced server-side to prevent nuking recent history). Single call deletes at most 5000 rows; rerun if more remain. Returns { deleted, retention_days }. Superadmin scope only.

Get the append-only ledger of every confidence change applied to a context (T359): each entry records the triggering link, a human-readable reason, and the old/new confidence values. Use this to audit WHY a context's belief confidence is what it is right now (see ctx_confidence_get for the current value) — e.g. 'why do we no longer trust this note' or 'what corroborated this claim'. Returns { results: [{id, contextId, triggeringLinkId, reason, oldConfidence, newConfidence, createdAt}] }, newest first. Returns an empty results array when the context isn't visible to the caller or has no recorde…

Compute the blast radius of a context BEFORE trusting a correction to it (T362): 'what breaks if this context turns out to be wrong'. Bounded BFS over context_links following derived_from/supersedes/implements edges downstream (same traversal shape as ctx_code_trace/ctx_provenance_get), plus a structural join against goal_nodes and a best-effort match against agent_lessons that reference the context. The exact same fan-out count gates whether the server's own automated supersede/archive/contradict decisions (memory-evolution, T352 contradicts links) auto-apply or are held for manual review — c…

Apply the same lifecycle move and/or archive flag to many contexts in a single call. Use this when you need to retire, mature, or reclassify a batch (capped at 200 ids per call). Tenant-scoped on the backend — ids belonging to other tenants are silently dropped and reported in the failed list. Returns { updated: number[], failed: { id, error }[] }.

List the block-level chunks for a context, ordered by chunk_index. Each chunk includes its heading_path, content, and has_embedding flag (false while the embedding job is still pending). Use this to inspect how a context was split for chunked retrieval, debug per-passage matches surfaced by ctx_search, or check embedding coverage before relying on semantic ranking.

Find every file that imports or calls a given source file. Returns the set of referencing files (with link type and callee-symbol hint) from the code graph stored in context_links. Use this instead of grep to answer 'what references X' — it reads from the pre-built graph rather than scanning the repo. `ref` can be a repo-relative file path (e.g. 'src/services/search.service.ts') or a numeric context id. Returns 404 when the file has not been indexed.

Trace the directional call chain FROM a given source file via BFS over CALLS edges in the code graph. Returns nodes and edges so you can reconstruct the call path. Use this to answer 'what does X call, and what do those files call' up to N levels deep — reads from the pre-built graph, not file content. `ref` can be a file path or numeric context id. `depth` controls BFS hops (default 2, max 3). Returns 404 when the file has not been indexed.

Get a context's current belief confidence (T359): a continuously-recomputed [0,1] score, distinct from epistemicStatus (a coarse write-time tag) and context_links.confidence (a static per-edge score). This one moves over time — corroborating derived_from links raise it, contradicts/supersedes links against it lower it, weighted by the linking source context's own confidence, and it slowly decays toward the neutral 0.5 prior if the context goes stale without new evidence. Returns { contextId, confidence, confidenceUpdatedAt, evidenceCount }. Use this to judge how much to trust a specific fact r…

List contradictions detected by the proactive contradiction hunter (T360) for the caller's tenant. Each row is a high-similarity context pair the LLM classifier judged as disagreeing, with severity, rationale, whether the T352 dispute flip actually applied or was held by the T362 blast-radius gate, and (when applied) the context_links id. Complements ctx_link (which disputes explicitly) -- this surfaces disagreements the hunter found on its own. Resolve via the existing POST /api/contexts/:id/resolve-contradiction route (ctx_get the disputed context id first if unclear which side is 'target').

Permanently delete a context entry by ID. This action cannot be undone. Use this only when you are sure the entry should be removed.

Diff a sandbox workspace's CURRENT rows against the snapshot it was forked from -- added/modified/removed/unchanged contexts, plus coarse counts for context_links and the goal graph. Use before deciding whether to apply a sandbox experiment's changes back to production (there is no auto-merge -- replay the accepted changes yourself, then ctx_discard_sandbox).

Hard-delete a sandbox workspace and everything in it (contexts, links, cloned goal nodes/deps). Irreversible. Sandboxes past their TTL are also swept automatically by a background job.

Run memory consolidation (dream) on a workspace's context entries. Clusters related entries using vector similarity, synthesizes each cluster into a 'synthesis' entry via LLM, and writes a dream log. Use dryRun to preview clusters without persisting. T497: dream on a large workspace (more than DREAM_ASYNC_THRESHOLD contexts, default 100) runs async — the response is { jobId, statusUrl } and you must poll ctx_ingest_status (or GET /api/ingest-jobs/:id) until status='succeeded' or 'failed' to read the full result. Small workspaces still return the full result inline. Pass async=true/false to fo…

Fetch an entity card from the knowledge graph: the entity's identity (name, aliases, type, summary), its current edges (facts currently believed true), and its full timeline (every fact ever extracted about it, including ones since invalidated/superseded, newest first). Use this to look up everything the graph knows about a specific entity id. Returns 404 when the entity does not exist under the authenticated tenant.

List the most recent context events (created / updated / archived / linked) from the in-memory ring buffer. Tenant-scoped — only events for the caller's tenant are returned. Useful for downstream agents that want to react to writes; the ring is capped at 200 envelopes server-side. Note: streaming subscriptions are HTTP-only via GET /api/events (Server-Sent Events) — MCP does not expose a streaming variant.

Re-run memory evolution for an existing context. Examines K=5 nearest neighbors and creates typed links / archives superseded notes via LLM judging. Use when you've updated a context substantially or want to recompute relationships. Pair with dry_run=true first to preview.

Explain WHY a search result was recalled by reconstructing the RRF (Reciprocal Rank Fusion) math for a captured retrieval trace: per-signal score breakdown (PG lexical rank + raw ts_rank, Elasticsearch BM25 rank + raw score, chunk cosine similarity, recency/tag/lifecycle/salience/confidence boost multipliers), the RRF-fused score, and the final rank -- for every result of that search, plus a human-readable narrative per result. Requires the server to have RETRIEVAL_TRACE_ENABLED=true and that this particular search was sampled in by RETRIEVAL_TRACE_SAMPLE_RATE -- this is a V1 observability sur…

Record a helpful/unhelpful verdict on a context that was returned by ctx_search (or POST /api/retrieve), closing the recall loop back into ranking. Pass the retrieval trace id from ctx_explain_recall (or from a search response's trace metadata) to join the verdict to the exact score breakdown it is about -- omit it if you don't have one, the verdict still records. Verdicts accumulate into a per-context, per-tenant adjustment (bounded by a small cap so no single client can reshape ranking) that folds into the T345 salience/reinforcement term the next time this context is retrieved. Tenant-scope…

Fork a throwaway SANDBOX workspace cloned from a snapshot (or a fresh snapshot of `workspace` taken on the fly). Mutate memory inside the sandbox freely -- production rows are never touched. Sandboxes are quota-capped per tenant and auto-expire after ttl_minutes (default from WORLD_SANDBOX_TTL_MINUTES). Returns {sandboxWorkspaceSlug, snapshotId, expiresAt, clonedCounts}.

Get a single context entry by its ID. Use this when you already know the exact context ID you want to read. Response includes lifecycle, atomic, quality_score, valid_from, and valid_to alongside the standard fields.

Entity-anchored fact search over the temporal knowledge graph. Resolves entities mentioned in the query (name/alias match, no LLM call), walks entity_edges 1-2 hops, and returns ranked facts with provenance (which context each fact came from) and validity (current vs. historical/invalidated). Use this to answer relationship questions ('who does X work for', 'what depends on Y') that plain text search can't reliably surface. Pass `as_of` for a point-in-time view of what was believed true at that date. Returns empty arrays (not an error) when no entities in the query resolve or the graph has no …

Run the deep health probe and return the full report. Probes DB, Elasticsearch, embedding provider, LLM provider, and scheduler states. 30-second in-memory cache on the server. Returns `{status, components, schedulers, queue}` - status is `ok|degraded|fail`. Useful for ad-hoc prod health checks from MCP clients.

Bulk import context entries from an external source. Optionally filter by workspace and preview with a dry run before committing.

Ingest raw material (URL or inline content) and turn it into atomic claims that get diff'd against the existing knowledge base. The server fetches/parses the source, extracts claims via LLM, runs kNN against the tenant + workspace scope, and decides create / update / archive per claim. Set dry_run=true to preview the plan without persisting any changes — recommended for the first call against a new source. Wave 13b: large or URL-sourced ingests run async — the response is { jobId, statusUrl } and you must poll ctx_ingest_status (or GET /api/ingest-jobs/:id) until status='succeeded' or 'failed…

Fetch the current status of an async background job. Generic poller (T497) — use this for the job id returned by ctx_ingest, ctx_remember, OR ctx_dream when any of them took the async path, until status='succeeded' or 'failed'. Returns counters (total_items, processed_items, failed_items), timestamps (created_at, started_at, completed_at), and on success the full result_summary (shape depends on which tool started the job: ctx_ingest/ctx_remember's created/updated/archived/skipped arrays, or ctx_dream's dream result).

Manually create a typed link from one context to another (supersedes/contradicts/implements/derived_from/related_to). The backend already auto-creates links during memory evolution; only call this tool when you want to assert a relationship the system missed or override it explicitly. The 'reason' arg is recorded as the link's created_by annotation for audit.

List typed links for a context — incoming, outgoing, or both. Use this to discover how a context is connected (what it supersedes, what supersedes it, what implements it, etc.) before making decisions about updates or archival. The `created_by` field on each link indicates origin: `wikilink:<raw title>` marks edges auto-created from `[[Wiki Title]]` tokens in the source content, `memory-evolution` marks LLM-judged edges, and other values are manual.

List context entries with optional filters. Use this to browse existing contexts by workspace, project, type, or tag without a search query.

Load one additional group of ContextQ tools into this session (group names come from ctx_tool_groups) so they become callable without reconnecting. Pass "all" to load every remaining ContextQ tool at once. Some MCP clients need to refresh their tool list to actually see newly loaded tools in the model's context -- if a loaded tool still doesn't show up, call it directly by name anyway (ContextQ accepts a tool call for any known tool name regardless of what tools/list currently returns), or restart this server with the environment variable CONTEXT_MCP_TOOL_PROFILE=full to get every tool from th…

List memory maps (Dream-generated multi-shape navigation TOCs) for the caller's tenant. Optionally filter by workspace / project slug. Each row carries `{id, shape, version, generatedAt, userEdited, scope}` - fetch the full map_payload via /api/maps/:id (not wrapped here yet to keep this surface small). Useful when listing or summarising available maps to an AI agent.

List recent memory-review verdicts (keep / retag / merge / archive / contradict / error). Each row records one LLM-judged review of a context during the periodic review-for-correctness ritual; verdicts are advisory unless 'archive' was auto-applied. Use this to audit what the reviewer has flagged and triage retag/merge/contradict candidates by hand. Superadmin scope only.

Manually trigger a one-shot memory review pass for a tenant. Samples a handful of older + well-connected contexts (default 5, env MEMORY_REVIEW_SAMPLE_SIZE), asks the LLM to verdict each, and persists results to memory_review_logs. Returns a summary with per-verdict counters and how many archives were auto-applied (only when LLM confidence > 0.8). Useful for ad-hoc audits without waiting for the scheduler. Superadmin scope only.

List Maps of Content (MOCs) for the tenant. MOCs are curated index notes that summarize and link to clusters of related contexts, providing a navigation layer over the knowledge graph. Use this to discover existing high-level views before creating new synthesis notes.

Idempotently get-or-create a project inside a workspace, matched on (workspace, slug). Returns the existing project or a new one. Call after ctx_workspace_ensure, passing the slug that call returned. Trigger: first-time project setup.

Walk the belief provenance chain backward from a context (T358): who/what produced it, and what it was derived from. BFS over context_provenance.source_context_ids, same traversal shape as ctx_code_trace. Returns { root: {id, name, epistemicStatus}, nodes: [{id, name, epistemicStatus}], edges: [{contextId, sourceContextId, transformType, producerId, modelId, promptHash, createdAt}], depth, truncated }. transformType is one of manual/agent_write/ingest/dream_synthesis/evolve. epistemicStatus is one of observed/told/inferred/assumed (weakest->strongest: assumed < inferred < told < observed) — us…

Regenerate Maps of Content by re-clustering the tenant's contexts and synthesizing one MOC per cluster via LLM. Expensive (runs an LLM call per cluster) — call sparingly, typically after a substantial batch of new contexts has been added. Requires admin scope.

Extract durable memories from a raw multi-turn conversation and save them as deduped atomic contexts. Turn-aware sibling of ctx_ingest: the server builds a speaker-attributed transcript, extracts only durable facts/preferences via LLM (skipping chit-chat), and runs the claims through the SAME kNN-dedup + diff + create/update/archive pipeline ctx_ingest uses. Pass subjectId to scope memories to a single end-user of your application (Mem0-parity user_id) — dedup then only considers that subject's own prior memories, and every created context is tagged with that subjectId so ctx_search (subjectId…

Convenience: resolve a saved search by name (caller's own row preferred, falling back to a tenant-shared row with the same name) and execute it. Use this when an agent has the human-readable name but not the id.

Save a new context entry (reference doc, feedback, project note, incident report, lesson learned, or user profile). Use this when you want to persist knowledge for future retrieval. Optional lifecycle/valid_from/valid_to flag the note's maturity and bi-temporal validity. Response includes atomic, quality_score, and lifecycle once the backend judge has run. Trigger: user asks you to remember/save something ("nhớ cái này", "lưu lại", "ghi nhớ giúp", "remember this", "save this", "note this down") — call whenever work-relevant info should persist across sessions. Only call when the request is act…

Create a new saved search. Supply a unique name (per owner within the tenant), an optional description, the search query string, and the filter blob. Set shared_with_tenant=true to let other users in the tenant see and run it.

Delete a saved search by id. Owner only — even tenant-shared searches can only be deleted by their original owner.

Fetch a single saved search by id. Returns 404 if it does not exist or the caller cannot see it (different tenant, or owned by another user and not shared).

List all saved searches visible to the caller (their own + tenant-shared). Saved searches are named, reusable retrieval views (Dataview-style) that bundle a query string with filters so agents/sessions can rerun them without re-typing the criteria.

Execute a saved search by id and return the same shape as ctx_search. Optional limit/offset/query overrides apply at run time without modifying the persisted view. Use this when you already know the saved search id.

Update an existing saved search. Owner can update their own searches; admins/owners can also update tenant-shared searches owned by others. Only the provided fields are changed.

Show the current active working scope (workspace + project) for this session/key, or 'ALL workspaces' when nothing is selected. Returns {workspace, project}.

Search / recall saved knowledge and memories using hybrid full-text + semantic search ranked by relevance — the default tool for 'what do I know about X' or 'did I already save this'. Use this when you need to find, remember, or look up existing knowledge by keyword or phrase. Set chunk_search=false to disable per-chunk passage matching, lifecycle_boost=false for legacy ranking, or include_archived=true to surface retired notes. Results may include lifecycle, quality_score, and matched_chunk per hit.

Take a content-addressed snapshot of a workspace's memory state (contexts, context_links, and its goal graph) at this moment. Returns {id, manifestHash, sourceWorkspaceId, ...} -- the snapshot id feeds ctx_fork_world for counterfactual replay or safe memory-surgery testing.

Get aggregate statistics: total context count, breakdown by workspace, type, tag, recently updated entries, and orphan_rate (notes with no tags and no inbound references). Use this for an overview of what is stored and to spot disconnected knowledge.

List additional groups of ContextQ tools not loaded in this session by default -- code-graph lookup, admin/audit, relay handoff, world-model snapshots, saved searches, knowledge-graph traversal, bulk import/ingest, and more. Search here first if a ContextQ tool you expect (a saved search, a relay, a snapshot, a code reference) is missing from your current tool list. Returns each group's name, one-line purpose, member tool names, and how many of them are already loaded, plus how to load a group with ctx_load_tool_group.

Undo a memory-evolution auto-archive within the configurable window (default 72h, env EVOLUTION_ARCHIVE_UNDO_WINDOW_HOURS). Only contexts archived by the memory-evolution feature qualify - manual PATCH lifecycle archives don't. Returns the restored context. Companion endpoint: ctx_undo_archive_info for eligibility check.

Check whether a context's auto-archive is still undo-able. Returns `{eligible: bool, archivedAt, expiresAt, archivedByFocalId, confidence, withinWindow}`. Use before ctx_undo_archive to surface a meaningful UX (button enabled/disabled, countdown to expiry) instead of round-tripping the undo attempt.

Update an existing context entry. Only the provided fields are changed; omitted fields remain unchanged. Use this to correct, append to, reclassify, or retire (archive) an existing entry. Optional lifecycle/valid_from/valid_to update note maturity and bi-temporal validity.

Select the active working scope (workspace + optional project) for this session/key. Subsequent reads default to this scope; writes resolve their target from it. Pass workspace=null (or omit) to clear back to ALL workspaces. Returns the resolved {workspace, project, persisted}. This is 'select the project/context to work with'.

Search the web through a configured provider (Tavily, Brave, or Serper). Use this when you need to look up current information online, find documentation for a live service, or search the internet for facts not in your training data. Tenant-scoped and gated behind WEB_SEARCH_ENABLED plus an active search credential. Optionally pipe results through ctx_ingest to persist them as knowledge base entries.

Idempotently get-or-create a workspace for this tenant: returns the existing one (created=false) or creates it (created=true). Safe to call repeatedly. The returned `slug` MAY DIFFER from the one you asked for — workspace slugs are globally unique, so a taken base gets a random suffix. Always persist the slug from the response and use THAT for every later call. Trigger: first-time project setup, "set up ContextQ for this repo".

List the workspaces this credential can write to (id, slug, name, context count, archived flag). Call this before ctx_workspace_ensure to check whether this project already has a workspace. Trigger: "which workspaces do I have", "list workspaces", "set up ContextQ here".

Add a node to the goal graph. Progressive elaboration: only title is required -- omit parent_id to create a root node (a vague node is created status='draft'); fill the rest as reality reveals it. kind: objective|milestone|goal|work_item|relay. owner_role/status/origin are free strings. Trigger: when a user (including a non-technical one) asks you to remember or hand off a piece of work for later ("thêm việc", "thêm task", "todo", "add a task", "add to the board"), create a node here with a valid status (draft is fine if details are vague) — this is how a casual request becomes a durable track…

Advance a node's status. A leaf moving to 'done' REQUIRES non-empty evidence (real observed output) — the no-self-certification rule. Parent status rolls up automatically from children. Trigger: when the user reports finishing a tracked piece of work ("xong rồi", "xong X", "done X", "done", "mark done", "finished X"), advance the matching board node's status here. Only call when the report maps to a tracked board item; ignore unrelated casual chatter.

Atomically claim a work-item node for your session, so two agents on DIFFERENT MACHINES cannot pick up the same task. Losing is a normal answer, not an error: the response is {claimed:false, heldBy:<session id>} naming who holds it — act on that, do not retry. Use before starting work on a node from goal_frontier when other agents may be running. Release with goal_release when you stop.

LLM-expand a goal node into child nodes + dependencies, self-checked by a judge before writing (no garbage on fail). `size` is an ADVISORY granularity hint for the LLM only (small=coarse/fewer children, medium=default/today's behavior, large=fine-grained/more children) — never a hard count enforced by the judge, since decomposition quality beats an exact node count. Returns {proposed, applied, reason, objective_run_id} — applied children share the parent objective's run id (lazily assigned on first decompose if the objective predates run-id tagging). If no LLM is configured returns applied=fal…

The ready-frontier: nodes (optionally for a role, or scoped to one objective_run_id) whose ALL blocking dependencies are done and that aren't done yet — i.e. 'what can I start NOW'. Returns GoalNode[] with depsIn/depsOut ([{nodeId, kind}]). A node whose externalRef.blocker is set is waiting on a person or an external event, not on a dependency: treat it as not runnable.

Get one goal node with its why-path (walk up to the objective) and its in/out dependency edges. Returns {node, why_path, deps_in, deps_out, duplicates} — `duplicates` lists tombstones merged into this node (externalRef.duplicate_of = its local_id); `node.objective_run_id` (and the objective's own entry in why_path) identifies the run whose activity_logs tell this node's whole objective story.

Bulk-import an existing backlog (CSV, e.g. a Jira export) into a living goal tree: parses to nodes, builds the containment tree from epic/phase columns, maps roles from issue type/assignee, and INFERS implicit cross-role dependencies (e.g. an FE task that needs a BE task). Tolerates messy data. Returns {created, deps, nodes}.

Create a dependency edge between two goal nodes (the DAG that cuts across the containment tree). kind='blocks' (from blocks to) or 'informs'. Rejected with a cycle error if it would make the graph cyclic.

List goal nodes, filtered. Use to read the graph (your lane, a status column, all milestones, or one objective's whole run via objective_run_id). Returns a COMPACT view by default (id, title, status, kind, externalRef.local_id/priority, blocked, depsIn/depsOut) and omits done nodes unless include_done is true or a status filter is given; call goal_get for one node's full payload, or pass view="full".

Release a claim your session holds on a node, freeing it for another agent. Conditional on you being the holder: releasing a node you do not hold reports {released:false} rather than failing, and never takes someone else's claim away. Call it when you stop work on a node you did not finish.

Set (or fetch) the north-star objective for a project — the root of the goal graph everything hangs off. Returns the kind='objective' node, which carries an `objective_run_id` — a run id lazily assigned once and then shared by every subsequent goal_add/goal_advance/goal_link_dep/goal_decompose/goal_import/goal_sync mutation under this objective. Query activity_logs (or goal_list/goal_frontier with objective_run_id) by that value to reconstruct this objective's whole activity story, the same way Claude Code's workflow.run_id reconstructs one workflow run.

Advance a relay's lifecycle: open -> claimed -> delivered -> verified -> closed (delivered -> claimed = kickback). 'verified' REQUIRES evidence. Illegal transitions are rejected. Pass session_id to enable the identity-reuse guard: if a DIFFERENT attested agent identity now holds this session than the one that claimed the relay, the advance is flagged (default, response + audit log) or rejected with a retarget error (RELAY_IDENTITY_GUARD_MODE=strict). Omit session_id to skip the guard entirely.

Claim a relay (atomic, first-write-wins). If already claimed, returns claimed=false with heldBy=<session id> so you skip it (no double-work). Returns {relay, claimed, heldBy}.

Fetch one directed cross-role relay/handoff (a baton passed between roles, e.g. frontend to backend) by id. Returns the kind='relay' GoalNode with its status, payload, and claim state. Use once you already have a relay id from relay_open or relay_inbox and want its full detail.

List relays addressed to a role (your inbox). status='open' by default; include_all=true also shows claimed relays (in progress by another session). Returns GoalNode[] (kind='relay').

Nudge a stuck 'claimed' relay to wake the holder (only 'claimed' relays can be nudged). Increments a per-relay nudge count; once it reaches the tenant's threshold (default 3), the same call auto-releases the claim back to status='open' so another session can pick it up. Returns {relay, released, nudgeCount, threshold}. If your runtime supports cross-session messaging and the holder's session is locally reachable, send it a native ping alongside this call for a real-time wake instead of waiting on its next poll.

Open a directed relay (a baton from one role to another, e.g. FE -> BE for an API contract). Built-in kinds: api_contract (frontend->backend), design_handoff (design->frontend); or pass from_role/to_role explicitly. Any role/agent name works immediately, no prior registration or setup call needed -- an unseen role is addressable on its very first relay_open. Born status='open', unclaimed. If your runtime supports cross-session messaging (e.g. Claude Code's ListAgents/SendMessage), consider pinging a plausibly-matching local session right after opening -- relay_inbox stays the source of truth, …