<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 Binary (Go)

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

```bash
# Initialize
pass_mgr admin init [--key-path <path>]

# Get password
pass_mgr get <key> [--username]

# Generate password (agent can use)
pass_mgr generate <key> [--username <user>]

# Set password (human only)
pass_mgr set <key> <password> [--username <user>]

# Delete password
pass_mgr unset <key>

# Rotate password
pass_mgr rotate <key>
```

**Security Features:**
- Agents cannot execute `set` (detected via environment variables)
- All operations fail before initialization
- Admin password leak detection (monitors messages/tool calls)

### 2. pcexec - Safe Execution Tool (TypeScript)

Compatible with OpenClaw native exec interface, automatically handles `pass_mgr get` and sanitizes output.

```typescript
import { pcexec } from 'pcexec';

const result = await pcexec('echo $(pass_mgr get mypassword)', {
  cwd: '/workspace',
  timeout: 30000,
});
// Passwords in result.stdout will be replaced with ######
```

### 3. safe-restart - Safe Restart Module (TypeScript)

Provides agent state management and coordinated restart.

**Agent States:**
- `idle` - Idle
- `busy` - Processing messages
- `focus` - Focus mode (workflow)
- `freeze` - Frozen (not accepting new messages)
- `pre-freeze` - Preparing to freeze
- `pre-freeze-focus` - Preparing to freeze (focus mode)

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

**Slash Commands:**
```
/padded-cell-ctrl status
/padded-cell-ctrl enable pass-mgr|safe-restart
/padded-cell-ctrl disable pass-mgr|safe-restart
```

## Project Structure

```
PaddedCell/
├── pass_mgr/           # Go password manager binary
│   ├── src/
│   │   └── main.go
│   └── go.mod
├── pcexec/            # TypeScript safe execution tool
│   ├── src/
│   │   └── index.ts
│   ├── package.json
│   └── tsconfig.json
├── safe-restart/      # TypeScript safe restart module
│   ├── src/
│   │   ├── index.ts
│   │   ├── status-manager.ts
│   │   ├── api.ts
│   │   ├── safe-restart.ts
│   │   └── slash-commands.ts
│   ├── package.json
│   └── tsconfig.json
├── docs/              # Documentation
├── PROJECT_PLAN.md    # Project plan
├── AGENT_TASKS.md     # Task list
├── README.md          # This file (English)
└── README.zh-CN.md    # Chinese version
```

## Installation

```bash
# Install
node install.mjs --install

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

## Usage

### pass_mgr

```bash
# Initialize (required before first use)
~/.openclaw/bin/pass_mgr admin init

# Set password
~/.openclaw/bin/pass_mgr set mykey mypassword

# Get password
~/.openclaw/bin/pass_mgr get mykey
```

## License

MIT