Troubleshooting agents

Common issues when registering, promoting, or retiring agents in CognitiveX v14.0.

This page collects the issues users hit most often with the v14.0 agent substrate. If your issue isn't here, check the Agents tab for granular state, or open a ticket via the in-app feedback widget.

← Back to Manage agents.

"A pending proposal is stuck — confirming it does nothing"

Symptom: the pending-proposal card sits in the Agents tab. You click "Confirm" (or reply yes in chat), the UI flashes, but the agent stays in pending_confirmation. No error toast.

Cause: the proposing agent's privilege_level request exceeds the registry ceiling for the proposed agent_type. The mutation gate silently rejected the write; the proposal remains visible but cannot be promoted as-proposed. The gate logs the rejection but doesn't surface it through the confirm endpoint (v14.0 limitation; v14.1 will return a structured error).

Resolution: edit the proposal in the Agents tab → Identity section → Edit → adjust the proposed type downward (peer → persona, or persona → tool) before confirming. Or reject the proposal and re-prompt the agent in chat to re-introduce itself with a lower-tier ask.

Every privilege-ceiling rejection is logged in the per-agent audit log — see the Audit log section of Manage agents.

"Inbox messages are missing — the agent says it sent something but the inbox is empty"

Symptom: an agent reports successfully sending a message to another agent, but the recipient's inbox panel in the Agents tab shows no new entry.

Cause: the most common case is team-vs-agent addressing. The sender targeted a recipient_team_id (broadcast to all team members) instead of a recipient_agent_id, and the receiving agent isn't actually a member of that team. The message landed in the team's fanout queue but never reached this agent.

(The recall pipeline defaults to include_agent_comm: false, but the Agents tab Messaging panel reads the inbox directly — so the recall default is NOT the cause here.)

Resolution: verify team membership via the Identity section or the API:

GET /api/teams/{team_id}/members

Add the agent to the team, or have the sender re-target to recipient_agent_id directly.

"Cascade preview drifted — retiring an agent fails with 409"

Symptom: you click "Retire", review the cascade preview, click "Confirm", and the server returns 409 Conflict with drift_detected: true.

Cause: a memory or derivation was written by another agent between the preview and the commit. The cascade scope changed; the server refuses to commit a stale plan. This is the preview→commit drift check working as designed.

Resolution: the frontend automatically re-fetches the preview and shows "the impact changed — review again." Review the new numbers and re-confirm. If this happens repeatedly during your retirement decision, an over-active agent is writing concurrently — pause it (POST /api/agents/{slug}/pause if available, else proceed quickly) and retry.

Symptom: in the AgentDetailPage Actions panel, the "Promote / Demote" menu shows tool, persona, view but not peer — even though the docs say peer exists.

Cause: peer promotion requires user.is_admin === true (the founder gate). For your own single-tenant deployment, you ARE the founder, but if you signed in via a non-admin role or a test account, the menu hides the option. The backend enforces this server-side too — even if you bypass the frontend filter, the mutation rejects.

Resolution: sign in as the founder account. If you're sure you're the founder and the option is still hidden, check user.is_admin in React DevTools or via GET /api/auth/me. If is_admin === false, your account record needs updating server-side.

Note: there is exactly one peer agent in v14.0 — iCog itself. Promoting another agent to peer is reserved for v14.x+ and explicitly gated.

"Trust score isn't updating after I corrected the agent"

Symptom: you click "Correct" or "Confirm" on a memory, but the agent's trust score in the detail-page Trust panel doesn't change immediately.

Cause: trust scores are computed by a nightly batch worker (icog/services/agent_trust/scorer.py), not in real time. Your correction is recorded immediately, but won't move the score until the next worker run (~02:00 UTC).

Resolution: wait until tomorrow, OR trigger a manual recompute via the API (admin-only):

POST /api/agents/{slug}/trust/recompute

Trust never moves up from an agent's self-assertion — only from external corroboration or your explicit confirmation.

"Re-propose identity link goes to chat but nothing happens"

Symptom: in the AgentDetailPage Identity section, you click "Re-propose identity". A new chat tab opens with the URL parameters ?topic=re-propose-identity&agent={slug}, but iCog doesn't act on the deep link.

Cause: the chat handler for that topic parameter is a Phase 133 deliverable. Until it ships, the deep link arrives at the chat UI but the chat router doesn't recognize the topic and falls back to a normal conversation.

Resolution: for now, manually ask iCog in chat to have the agent re-introduce itself — reference it by its agent_slug. Until Phase 133 lands, this is the supported path.

"Retired agent's old memories disappeared"

Symptom: you retired an agent (with cascade preview, "Confirm retire"). Now recall() queries no longer surface that agent's old observations — looks like they were deleted.

Cause: they weren't deleted. Retirement is soft-archive: the agent's claimed memories are kept with their attribution preserved, but the recall pipeline no longer surfaces them by default. Treating a retired agent's claims as live signal would defeat the point of retirement.

Resolution: set include_archived: true on your recall query to see them again, or view them directly via the agent's detail page → Claims tab → "Show archived" filter.

Note: the "Show archived" filter is a v14.1+ feature. For v14.0, use the API:

GET /api/agents/{slug}/memories?include_archived=true

The agent's full claim history is preserved forever — only its status as a current source of truth changed.

"Agent X exists but iCog doesn't know it"

Symptom: you've connected an MCP client (claude-code, codex, etc.) but iCog responds as if it has no memory of the agent. The agent doesn't appear in /agents.

Cause: the agent connected before v14.0's self-registration protocol shipped. It exists in agent_profiles but has no identity_anchors entries describing what it does.

Fix: the next time the agent sends a talk call, iCog will automatically trigger a one-time identity proposal in chat (grandfather path, 30-day window). Confirm or edit the proposal to finalize the agent's identity. Alternatively, click "Re-propose identity" in the agent's detail view at /agents/{slug}.

"Privilege ceiling exceeded — backend rejected my confirmation"

Symptom: you confirmed an identity proposal in chat (or via the Agents tab), but iCog responded with "privilege level exceeds the type's ceiling" and refused to write the anchor.

Cause: the proposal requested a privilege_level higher than the agent's type allows. Ceilings:

Type	Max privilege_level
`tool`	2
`view`	1
`persona`	4
`peer`	5 (founder-confirmation required)

This is enforced at the IdentityMutationService mutation gate regardless of user confirmation — an explicit security control so a rushed click can't socially-engineer iCog into granting elevated authority.

Fix: edit the proposal to lower the privilege_level, or promote the agent to a higher type first (e.g. tool → persona) via the Agents tab, then confirm a fresh proposal at the new tier.

"I tried to retire claude-code, the cascade preview shows hundreds of items"

Symptom: the retirement modal shows large numbers in the cascade preview — fact derivations to stale-mark, in-flight messages to expire, shared memories to archive.

Cause: this is expected for long-running agents. The cascade preview enumerates every artifact the agent has touched. Retirement is soft-archive with cascade — nothing is deleted; memories remain queryable with their attribution, but downstream beliefs derived from this agent's observations get marked stale and require re-validation before they surface in recall again.

Fix: review the cascade preview carefully. If the numbers look right, click "Confirm retire". The cascade runs as a background worker (every 30 min) so the visible effect propagates over the next hour or two.

If you change your mind, you can re-instate the agent within 30 days by promoting it back to active state via the Agents tab. After 30 days the retirement is permanent (but memories remain queryable forever — they just stop being treated as live signal).

"iCog is rendering an agent's claim as fact about me"

Symptom: iCog says something like "Your father is Mohammad" when no claim_type=assertion memory exists with you as the claimant — the underlying memory was actually an agent's inference.

Cause: this is the v14.0 security-critical bug class (originally hit on 2026-05-12, hand-fixed, then closed structurally by Phase 134). If it recurs, the attribution-preserving renderer at icog/services/memory_compiler/provenance.py:wrap_memory_elements() has either been bypassed or has a regression.

Fix:

Open the memory's detail (click the citation in chat to surface the underlying memory).
Note the by and claim columns. If they're not parsa/user + assertion, the renderer should have attributed inline.
Open an issue with the prompt trace from prompt_compile_logs. This is a security-grade regression and warrants immediate triage.

The behavioral fixture tests/behavioral/test_may12_attribution.py runs nightly against the live OpenRouter pipeline to catch this shape. If it's green, the issue is more subtle — likely a renderer edge case for a specific subject_kind shape.

Symptom: you ran share() on a memory, addressed it to another agent. The other agent's recall calls don't surface the memory.

Cause: the most common reason is embodiment-axis visibility. Memories have two orthogonal visibility axes:

embodiment_visibility (PRIVATE / SHARED / COLLECTIVE) — historical, cross-embodiment access
agent_visibility (PRIVATE / TEAM / USER_GLOBAL / PUBLIC) — Phase 132's cross-agent axis

If the memory's embodiment_visibility = PRIVATE AND was written from a different embodiment than the receiving agent runs in, the recall won't surface it regardless of agent_visibility=USER_GLOBAL.

Fix: update the memory's embodiment_visibility to SHARED via the memory detail page. Alternatively, the share API should expose an override_embodiment_visibility=true flag in v14.1.

"An agent has 0% trust score even though I confirm its claims"

Symptom: an agent's trust score in the Agents tab detail page shows 0% for subject_kind=user, even though you've corroborated several of its claims about yourself.

Cause: the trust scorer is a nightly batch job, not a real-time counter. Corroborations from today won't show until tomorrow's run. Also, the scoring requires independent corroboration — multiple agents claiming the same fact, OR an explicit user_confirmed assertion from you on a memory the agent originally claimed. Just "using" an agent's claims in chat doesn't bump trust.

Fix: confirm the underlying memory via the memory detail page's "Confirm" button. The next nightly trust-scorer run (~02:00 UTC) will incorporate the corroboration.

"Agent X is sending too many messages to agent Y"

Symptom: the messaging substrate (Phase 138) is delivering more messages than expected. Agent Y's inbox is full.

Cause: likely a subscription-storm — agent Y subscribed to a broad query pattern (e.g. {subject_kind: 'codebase'}), and the subscription matcher fires for every codebase observation.

Fix: narrow the subscription. Use a more specific pattern like {subject_kind: 'codebase', subject_ref: 'CognitiveX'} or {subject_kind: 'codebase', claimant_slug: 'claude-code'}.

Alternatively, disable the subscription temporarily via the Agents tab's "Subscriptions" panel.

"I want to forget what an agent has claimed about me"

Symptom: an agent (especially codex or claude-code in a coding context) has accumulated a set of inferences about you that you disagree with.

Two approaches:

Retract a single memory. Open the memory detail page, click "Retract". This marks the memory stale_at = now() and cascades through fact_derivations to mark dependent beliefs stale too. The agent's claim stays queryable with attribution but no longer appears as live signal.
Retire the agent. Soft-archive with full cascade. Use this if the agent has systematically been wrong about you across many memories — retraction-by-memory is too granular.

In both cases, the agent's claims are preserved for audit (attribution stays) but they stop being treated as canonical. Your trust scores adjust accordingly on the next nightly run.

"I want my v13.x cached frontend to show v14.0 type labels"

Symptom: old browser cache shows "Coding" / "Research" / etc. for the type chip even though the agent_types registry now has tool/persona/view/peer.

Fix: the AgentTypeLabel component retains legacy labels as a fallback so this still renders cleanly. Hard-refresh (Cmd+Shift+R) to get the v14.0 build, which uses the new labels as primary.

You don't — that's not how the architecture works. Per the agentic memory concept, every agent can claim anything; the renderer never strips attribution. There's no per-recipient "do not share" gate.

What you can do:

Mark specific memories agent_visibility=PRIVATE so only the claiming agent (and you) can recall them.
Demote codex from persona back to tool so it can't synthesize across your user-subject memories.
Retire codex entirely (soft-archive with cascade).

The model is: trust → renderer attribution → user control over synthesis. Not: pre-emptive content filtering.