Initialize Ketan-OS for a workspace directory. This MUST be called before any other Ketan-OS tools if you are switching workspaces. Creates a KetanHarness that manages transactional snapshotting, invariant enforcement, and causal tracing for the given workspace.

Args: workspace_path: Absolute path to the project/workspace directory to protect.

Get the current Ketan-OS ground-truth state report. Returns step count, checkpoint count, CTG node/edge counts, failure count, and workspace directory.

Take an atomic filesystem snapshot of the entire workspace. Creates a checkpoint you can roll back to if anything goes wrong. Always call this before a risky sequence of operations.

Returns the checkpoint ID you can use with ketan_rollback.

Time-travel rollback the workspace to a previous checkpoint. Reverts ALL filesystem changes (file writes, deletions, renames) that occurred after that checkpoint was taken, in sub-second time.

Args: checkpoint_id: The checkpoint ID to roll back to (from ketan_get_checkpoints or ketan_snapshot).

List all available checkpoints in the Ketan dual-ledger (newest first). Each checkpoint captures the full workspace filesystem state and conversation prompt stack, enabling atomic rollback to any point.

Write a file to the workspace with FULL Ketan-OS protection:

1. Pre-flight invariant guard: Python AST syntax check for .py files, dangerous pattern detection.

2. Atomic snapshot of current workspace state before writing.

3. Write the file.

4. On any failure → automatic rollback to pre-write state.

Always prefer this over direct file writes for safe, reversible mutations.

Args: filepath: Path relative to workspace root (e.g., "src/main.py") content: Full file content to write

Execute a shell command with FULL Ketan-OS protection:

1. Pre-flight dangerous command guard (blocks rm -rf /, fork bombs, etc.).

2. Atomic snapshot before execution.

3. Run the command in the workspace directory.

4. On non-zero exit or exception → automatic rollback to pre-command state.

Always prefer this over raw bash for state-changing commands.

Args: command: Shell command to run (executed in workspace directory) timeout_seconds: Maximum execution time before timeout (default: 30s)

Run a pre-flight invariant check WITHOUT executing anything. Validate a planned action before committing to it.

Args: tool_name: Name of the tool you plan to call (e.g., "write_file", "bash") tool_args_json: JSON string of the arguments you plan to pass

Get the Causal Trace Graph (CTG) as a Mermaid diagram. The CTG is a live DAG showing every tool call, checkpoint, failure, and rollback in the session with causal edges between them. Paste the output into mermaid.live to visualize it.

Get a root-cause explanation of the most recent failure in the CTG. Traces the exact execution chain that led to the failure. Returns a clean message if no failures exist.

Record a factual observation into the Epistemic Belief Engine. The engine tracks beliefs about the workspace and detects contradictions (e.g., "tests pass" followed by "tests fail") to prevent hallucination loops.

Args: subject: What the belief is about (e.g., "tests/test_main.py") predicate: The relationship (e.g., "exists", "passes", "contains_bug") value: The observed value (e.g., "true", "false", "syntax_error") confidence: Confidence level 0.0–1.0 (default 1.0)

List all active beliefs tracked by the Epistemic Belief Engine. These are facts observed about the workspace during this session.

Read a file from the workspace. Also records its existence as a belief.

Args: filepath: Path relative to workspace root (e.g., "src/main.py")

List all files in the workspace (or a subdirectory of it).

Args: subdirectory: Optional subdirectory relative to workspace root (default: root)

Get a complete markdown summary of the Ketan-OS session: steps taken, checkpoints created, failures recorded, beliefs tracked.