Coordination & Governance

Activity Ledger & Surgical Undo

Every file edit, file creation, deletion, and shell command executed by your coding agents is captured in a bounded ring buffer with SHA-256 state verification and out-of-order surgical rollback.

1,000-Turn Ring BufferSurgical Reverse PatchLIFO Batch RewindProcedural Undo Recipes
01 · Deterministic Audit Trail

Bounded Mutation Ring Buffer

Sulcus records pre-mutation and post-mutation file snapshots (up to 256 KB by default, configurable from 4 KB to 10 MB) alongside exact edit hunks and Git working-tree deltas.
Control Panel · Ledger & Triggers -> Activity Ledger & Surgical Undo
Sulcus Control Panel Activity Ledger showing recorded file_edit and run_command turns with Surgical Undo buttons
Each mutation receives a monotonic sequence ID (#seq_id), SHA-256 pre/post state hashes, and one-click Surgical Undo without discarding unrelated work performed in later turns.
Capacity & Retention

50 to 50,000 Turns

Defaults to max_entries = 1000 per namespace. Files larger than max_snapshot_bytes (256 KB default) strip raw content automatically while preserving sha256 and size_bytes.

Recorded Action Types

Files, CLI & MCP

Tracks file_edit, file_write, file_create, file_delete, run_command, and mcp_mutation across all connected harnesses.

Bus Synchronization

Peer Rewind Signals

Executing an undo on the Sulcus API emits rewind.started and rewind.completed on the Agent Bus so peer agents refresh stale file context immediately.

02 · Reversal Mechanics

How Surgical & Compensating Undo Works

Batch rewinds always sort selected entries by seq_id DESC (strictly LIFO) so dependent edits and shell commands unwind in exact reverse chronological order.

File Mutation Strategies

  1. delete_created_file: When pre_state.existed == false, Sulcus removes the newly created path and verifies removal on disk.
  2. surgical_reverse_patch: When later turns modified the same file (post_state.sha256 != current_sha) and diff_hunksare recorded, Sulcus reverses only that turn's exact hunks while preserving non-overlapping edits made afterward.
  3. pre_image_restore: When no subsequent edits occurred (post_state.sha256 == current_sha), Sulcus restores pre_state.content and verifies the resulting SHA-256 digest matches pre_state.sha256.

CLI Command 3-Tier Cascade

  1. procedural_recipe_replay: Checks memory for a verified [Undo Recipe: ...] procedural node matching the command prefix.
  2. llm_compensating_cli: On cloud deployments when llm_cli_undo_enabled is active (automatically disabled on air-gapped and connected on-prem appliances), synthesizes a verified compensating command.
  3. compensating_cli: Deterministic fallback reversing mv, cp, untracked Git artifacts, sqlx migrate run, and git branch. Successful CLI reversals are stored as procedural recipes (heat = 0.92) for instant reuse.
Command Safety Guard & Local vs. Cloud Selection

Every compensating CLI command passes is_command_safe, which strictly blocks compound shell operators (;, &&, ||, backticks, $(...)) and destructive patterns (rm -rf /, git reset --hard, git push --force, DROP DATABASE).

On the local sulcus engine, POST /api/v1/agent/ledger/undo supports seq_ids, last_n, substring query filtering, and dry_run. On the remote Sulcus API, undo targets explicit seq_ids or last_n (1 to 100) and persists audit rows in undo_history.

bashRecord a Mutation Snapshot
curl -X POST https://api.sulcus.ca/api/v1/agent/ledger/record \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "junie-rm-01",
    "harness": "rubymine",
    "namespace": "payments-rails",
    "action_type": "file_edit",
    "tool_name": "edit_file",
    "target_path": "services/billing/webhook_verifier.rb",
    "summary": "Enforce 300s timestamp drift ceiling",
    "pre_state": {
      "existed": true,
      "sha256": "9f4c1a8e...",
      "size_bytes": 1842,
      "content": "..."
    },
    "post_state": {
      "existed": true,
      "sha256": "3b81e044...",
      "size_bytes": 1996,
      "content": "..."
    },
    "diff_hunks": [
      {
        "start_line": 42,
        "target_excerpt": "MAX_DRIFT = 86_400",
        "replacement_excerpt": "MAX_DRIFT = 300"
      }
    ]
  }'
bashSurgical Out-of-Order & LIFO Undo
# Surgical out-of-order undo of specific sequence IDs (unwound in strict LIFO order)
curl -X POST https://api.sulcus.ca/api/v1/agent/ledger/undo \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "payments-rails",
    "seq_ids": [840, 842]
  }'

# Or rewind the last 3 mutations in the namespace
curl -X POST https://api.sulcus.ca/api/v1/agent/ledger/undo \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "payments-rails",
    "last_n": 3
  }'
bashTune Per-Namespace Ledger Retention
curl -X POST https://api.sulcus.ca/api/v1/agent/ledger/config \
  -H "Authorization: Bearer $SULCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "namespace": "payments-rails",
    "enabled": true,
    "max_entries": 2000,
    "retain_file_snapshots": true,
    "max_snapshot_bytes": 262144,
    "llm_cli_undo_enabled": true
  }'
03 · Protocol Reference

Activity Ledger Endpoints & MCP Tools

GET/api/v1/agent/ledger
List recorded ledger entries and active namespace config (?namespace, ?limit up to 500).
POST/api/v1/agent/ledger/record
Append a file, CLI, or MCP mutation with pre/post SHA-256 snapshots and diff_hunks.
POST/api/v1/agent/ledger/config
Configure enabled, max_entries (50..50000), retain_file_snapshots, max_snapshot_bytes, and llm_cli_undo_enabled.
POST/api/v1/agent/ledger/undo
Unwind mutations by seq_ids or last_n in strict LIFO order and learn procedural CLI undo recipes.
MCPlist_activity_ledger
Inspect recent tool mutations and sequence IDs from any MCP-connected agent.
MCPrecord_activity
Record a mutation entry directly over MCP.
MCPundo_activity
Trigger surgical file hunk reversal or LIFO batch rewind (alias: rewind_activity).
Reactive TriggersControl Panel Guide