<div align="center">

[English](README.md) | [简体中文](README.zh-CN.md)

</div>

# PaddedCell

OpenClaw plugin for secure password management, safe command execution, and coordinated agent restart.

## Features

### 1. pass_mgr — Password Manager (Go)

AES-256-GCM encryption, per-agent key-based encryption/decryption.

```bash
pass_mgr admin init            # Initialize
pass_mgr get <key>             # Get password
pass_mgr set <key> <password>  # Set password (human only)
pass_mgr generate <key>        # Generate password
pass_mgr unset <key>           # Delete
pass_mgr rotate <key>          # Rotate
```

### 2. pcguard — Exec Guard (Go)

Validates that a process is running inside a pcexec context by checking environment sentinels (`AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE`). Returns exit code 1 with error message if any check fails.

Scripts can call `pcguard` at the top to ensure they're executed via pcexec:

```bash
#!/bin/bash
pcguard || exit 1
# ... rest of script
```

### 3. pcexec — Safe Execution Tool (TypeScript)

Drop-in replacement for `exec` that:
- Resolves `$(pass_mgr get key)` inline and sanitizes passwords from output
- Injects `AGENT_VERIFY`, `AGENT_ID`, `AGENT_WORKSPACE` environment variables
- Appends `$(openclaw path)/bin` to `PATH` (making `pcguard` and `pass_mgr` available)

### 4. safe-restart — Coordinated Restart (TypeScript)

Agent state management and coordinated gateway restart.

**Agent States:** idle → busy → focus → freeze → pre-freeze

**APIs:**
- `POST /query-restart` — Query restart readiness
- `POST /restart-result` — Report restart result
- `GET /status` — Get all statuses

## ⚠️ Security Limitations

> **PCEXEC + PCGUARD only mitigate light model hallucination / misoperation / prompt forgetting.**
> They **do not** defend against malicious attacks.
> For stronger security, use **sandbox mode** instead of this plugin.

## Project Structure

```
PaddedCell/
├── plugin/              # Plugin source (TypeScript)
│   ├── commands/        #   Slash commands
│   ├── core/            #   Core modules (safe-restart, status, api)
│   ├── hooks/           #   Lifecycle hooks
│   ├── tools/           #   Tool definitions (pcexec)
│   ├── index.ts         #   Plugin entry point
│   ├── openclaw.plugin.json
│   ├── package.json
│   └── tsconfig.json
├── pass_mgr/            # Go password manager binary
│   └── src/main.go
├── pcguard/             # Go exec guard binary
│   └── src/main.go
├── docs/                # Documentation
├── scripts/             # Utility scripts
├── dist/padded-cell/    # Build output
├── install.mjs          # Installer
└── README.md
```

## Installation

```bash
# Install (default: ~/.openclaw)
node install.mjs

# Install with custom openclaw profile path
node install.mjs --openclaw-profile-path /path/to/.openclaw

# Build only (no install)
node install.mjs --build-only

# Uninstall
node install.mjs --uninstall
```

### Install paths

The installer resolves the openclaw base path with this priority:
1. `--openclaw-profile-path` CLI argument
2. `$OPENCLAW_PATH` environment variable
3. `~/.openclaw` (default)

Binaries go to `$(openclaw path)/bin/`, plugin files to `$(openclaw path)/plugins/padded-cell/`.

## Usage

```bash
# Initialize pass_mgr
~/.openclaw/bin/pass_mgr admin init

# Set and get passwords
~/.openclaw/bin/pass_mgr set mykey mypassword
~/.openclaw/bin/pass_mgr get mykey

# Use pcguard in scripts
pcguard || exit 1
```

## License

MIT