Skip to main content

​
Overview

The codaph repair cloud command repairs missing or inconsistent cloud synchronization by replaying your local .codaph mirror to Mubit, then republishing shared session and diff artifacts.
This is a recovery tool for when cloud sync fails or events are missing from Mubit. Your local mirror is the source of truth.

​
When to Use Repair Cloud

  • Cloud sync interrupted: Network issues or API errors prevented events from reaching Mubit
  • Missing sessions: Sessions appear locally but not in collaborative context
  • Artifact republish: Session summaries or diffs need to be regenerated in Mubit
  • Mubit setup changed: Switched project IDs or run scopes and need to backfill

​
Basic Usage

codaph repair cloud
This scans your local .codaph mirror, replays all events to Mubit, and republishes session artifacts.

​
Workflow

​
1. Backfill Phase

The repair process reads your local JSONL mirror and replays events to Mubit:
  • Scans all sessions in .codaph/sessions/
  • Reads canonical event envelopes from JSONL files
  • Writes events to Mubit with deduplication
  • Handles concurrent write batching for performance

​
2. Artifact Republish Phase

After backfill completes, shared artifacts are regenerated:
  • Session summaries: Written to codaph:<project>:session-summary run
  • Diff artifacts: Written to codaph:<project>:diff run
  • Prompt timeline: Written to codaph:<project>:prompt run
These artifacts enable semantic search and collaborative context across contributors.

​
Options

​
--cwd
string
Working directory (defaults to current directory)
​
--session
string
Repair only a specific session ID (filter)
​
--json
boolean
Output summary in JSON format
​
--verbose
boolean
Show detailed progress for each event

​
Examples

​
Repair All Sessions

codaph repair cloud
Output: 
Repair (cloud): backfill sessions=12 attempted=348 accepted=348 dedup=0 failed=0
Repair (cloud): artifacts republished sessions=12 events=48

​
Repair Single Session

codaph repair cloud --session abc123de
Only events from the specified session are replayed to Mubit.

​
JSON Output

codaph repair cloud --json
Output: 
{
  "schema": "codaph.repair-cloud.v1",
  "cwd": "/Users/you/project",
  "repoId": "owner/repo",
  "sessionFilter": null,
  "backfill": {
    "scannedSessions": 12,
    "attempted": 348,
    "accepted": 348,
    "deduplicated": 0,
    "failed": 0
  },
  "artifacts": {
    "sessionsPublished": 12,
    "artifactEvents": 48
  }
}

​
Architecture Details

​
Event Source

Repair cloud reads from your local JSONL mirror (src/lib/mirror-jsonl.ts:74):
  • Mirror maintains manifest, sparse indexes, and eventId deduplication
  • Events stored as canonical CapturedEventEnvelope with eventId, source, repoId, actorId, sessionId, threadId, ts, eventType, payload
  • Source is append-only and deterministic

​
Mubit Write Pipeline

Events flow through the ingest pipeline (src/lib/ingest-pipeline.ts:14): 
MirrorEvent → Redact → Canonicalize → Mubit.writeEvent()
  • Redaction: Sensitive data stripped via redactUnknown() (src/lib/security.ts:26)
  • Deduplication: Based on eventId hash
  • Batching: Concurrent writes with configurable batch size and timeout
  • Circuit breaker: Fail-open after consecutive errors (local mirror unaffected)

​
Mubit Run Scopes

Repair respects your configured run scope (src/lib/memory-mubit.ts:22):
  • Project scope: codaph:<projectId> — shared run across contributors/sessions
  • Session scope: codaph:<projectId>:<sessionId> — separate run per session
Artifacts published to:
  • codaph:<projectId>:prompt
  • codaph:<projectId>:session-summary
  • codaph:<projectId>:diff

​
Troubleshooting

Repair cloud requires a valid MUBIT_API_KEY. Run codaph doctor to verify your setup.

​
”Mubit is disabled”

Error: 
Mubit is disabled. Set MUBIT_API_KEY (or MUBIT_APIKEY) and use --mubit.
Fix: 
export MUBIT_API_KEY=your-key-here
codaph repair cloud
Or save globally: 
codaph setup --mubit-api-key your-key-here

​
High Deduplication Count

If dedup count is high, events were already in Mubit. This is normal after successful sync.

​
Failed Events

If failed > 0, check:
  • Network connectivity to Mubit API
  • API key validity (codaph doctor)
  • Mubit write timeout (default 15s): --mubit-write-timeout-ms 30000
  • codaph push — Import local agent history to Codaph mirror + Mubit
  • codaph pull — Sync Mubit cloud timeline back to local mirror
  • codaph doctor — Verify Mubit configuration and connectivity

​
Implementation

Source: src/index.ts:2547 (repairCloud function) Key modules:
  • src/mubit-remote-sync.ts:284 — syncMubitRemoteActivity (reverse: cloud → local)
  • src/lib/memory-mubit.ts:143 — MubitMemoryEngine.writeEvent
  • src/lib/mirror-jsonl.ts:74 — JsonlMirror append/read operations

Build docs developers (and LLMs) love

Get started for freeTalk to us